zsp/everything-claude-code
1
0
Fork 0
mirror of https://github.com/affaan-m/everything-claude-code.git synced 2026-03-30 13:43:26 +08:00
Code Issues Packages Projects Releases Wiki Activity

Revert "feat(ecc): prune plugin 43→12 items, promote 7 rules to .claude/rules/ (#245)"

Browse Source 
This reverts commit 1bd68ff534.
This commit is contained in:
Affaan Mustafa
2026-02-20 01:11:30 -08:00
parent 1bd68ff534
commit 0e9f613fd1
536 changed files with 111479 additions and 253 deletions
Download Patch File Download Diff File Expand all files Collapse all files

62
commands/build-fix.md Normal file
View File

@@ -0,0 +1,62 @@
# Build and Fix
Incrementally fix build and type errors with minimal, safe changes.
## Step 1: Detect Build System
Identify the project's build tool and run the build:
| Indicator | Build Command |
|-----------|---------------|
| `package.json` with `build` script | `npm run build` or `pnpm build` |
| `tsconfig.json` (TypeScript only) | `npx tsc --noEmit` |
| `Cargo.toml` | `cargo build 2>&1` |
| `pom.xml` | `mvn compile` |
| `build.gradle` | `./gradlew compileJava` |
| `go.mod` | `go build ./...` |
| `pyproject.toml` | `python -m py_compile` or `mypy .` |
## Step 2: Parse and Group Errors
1. Run the build command and capture stderr
2. Group errors by file path
3. Sort by dependency order (fix imports/types before logic errors)
4. Count total errors for progress tracking
## Step 3: Fix Loop (One Error at a Time)
For each error:
1. **Read the file** — Use Read tool to see error context (10 lines around the error)
2. **Diagnose** — Identify root cause (missing import, wrong type, syntax error)
3. **Fix minimally** — Use Edit tool for the smallest change that resolves the error
4. **Re-run build** — Verify the error is gone and no new errors introduced
5. **Move to next** — Continue with remaining errors
## Step 4: Guardrails
Stop and ask the user if:
- A fix introduces **more errors than it resolves**
- The **same error persists after 3 attempts** (likely a deeper issue)
- The fix requires **architectural changes** (not just a build fix)
- Build errors stem from **missing dependencies** (need `npm install`, `cargo add`, etc.)
## Step 5: Summary
Show results:
- Errors fixed (with file paths)
- Errors remaining (if any)
- New errors introduced (should be zero)
- Suggested next steps for unresolved issues
## Recovery Strategies
| Situation | Action |
|-----------|--------|
| Missing module/import | Check if package is installed; suggest install command |
| Type mismatch | Read both type definitions; fix the narrower type |
| Circular dependency | Identify cycle with import graph; suggest extraction |
| Version conflict | Check `package.json` / `Cargo.toml` for version constraints |
| Build tool misconfiguration | Read config file; compare with working defaults |
Fix one error at a time for safety. Prefer minimal diffs over refactoring.

74
commands/checkpoint.md Normal file
View File

@@ -0,0 +1,74 @@
# Checkpoint Command
Create or verify a checkpoint in your workflow.
## Usage
`/checkpoint [create|verify|list] [name]`
## Create Checkpoint
When creating a checkpoint:
1. Run `/verify quick` to ensure current state is clean
2. Create a git stash or commit with checkpoint name
3. Log checkpoint to `.claude/checkpoints.log`:
```bash
echo "$(date +%Y-%m-%d-%H:%M) | $CHECKPOINT_NAME | $(git rev-parse --short HEAD)" >> .claude/checkpoints.log
```
4. Report checkpoint created
## Verify Checkpoint
When verifying against a checkpoint:
1. Read checkpoint from log
2. Compare current state to checkpoint:
- Files added since checkpoint
- Files modified since checkpoint
- Test pass rate now vs then
- Coverage now vs then
3. Report:
```
CHECKPOINT COMPARISON: $NAME
============================
Files changed: X
Tests: +Y passed / -Z failed
Coverage: +X% / -Y%
Build: [PASS/FAIL]
```
## List Checkpoints
Show all checkpoints with:
- Name
- Timestamp
- Git SHA
- Status (current, behind, ahead)
## Workflow
Typical checkpoint flow:
```
[Start] --> /checkpoint create "feature-start"
|
[Implement] --> /checkpoint create "core-done"
|
[Test] --> /checkpoint verify "core-done"
|
[Refactor] --> /checkpoint create "refactor-done"
|
[PR] --> /checkpoint verify "feature-start"
```
## Arguments
$ARGUMENTS:
- `create <name>` - Create named checkpoint
- `verify <name>` - Verify against named checkpoint
- `list` - Show all checkpoints
- `clear` - Remove old checkpoints (keeps last 5)

40
commands/code-review.md Normal file
View File

@@ -0,0 +1,40 @@
# Code Review
Comprehensive security and quality review of uncommitted changes:
1. Get changed files: git diff --name-only HEAD
2. For each changed file, check for:
**Security Issues (CRITICAL):**
- Hardcoded credentials, API keys, tokens
- SQL injection vulnerabilities
- XSS vulnerabilities
- Missing input validation
- Insecure dependencies
- Path traversal risks
**Code Quality (HIGH):**
- Functions > 50 lines
- Files > 800 lines
- Nesting depth > 4 levels
- Missing error handling
- console.log statements
- TODO/FIXME comments
- Missing JSDoc for public APIs
**Best Practices (MEDIUM):**
- Mutation patterns (use immutable instead)
- Emoji usage in code/comments
- Missing tests for new code
- Accessibility issues (a11y)
3. Generate report with:
- Severity: CRITICAL, HIGH, MEDIUM, LOW
- File location and line numbers
- Issue description
- Suggested fix
4. Block commit if CRITICAL or HIGH issues found
Never approve code with security vulnerabilities!

183
commands/go-build.md Normal file
View File

@@ -0,0 +1,183 @@
---
description: Fix Go build errors, go vet warnings, and linter issues incrementally. Invokes the go-build-resolver agent for minimal, surgical fixes.
---
# Go Build and Fix
This command invokes the **go-build-resolver** agent to incrementally fix Go build errors with minimal changes.
## What This Command Does
1. **Run Diagnostics**: Execute `go build`, `go vet`, `staticcheck`
2. **Parse Errors**: Group by file and sort by severity
3. **Fix Incrementally**: One error at a time
4. **Verify Each Fix**: Re-run build after each change
5. **Report Summary**: Show what was fixed and what remains
## When to Use
Use `/go-build` when:
- `go build ./...` fails with errors
- `go vet ./...` reports issues
- `golangci-lint run` shows warnings
- Module dependencies are broken
- After pulling changes that break the build
## Diagnostic Commands Run
```bash
# Primary build check
go build ./...
# Static analysis
go vet ./...
# Extended linting (if available)
staticcheck ./...
golangci-lint run
# Module issues
go mod verify
go mod tidy -v
```
## Example Session
```text
User: /go-build
Agent:
# Go Build Resolution
## Initial Diagnostics
```bash
$ go build ./...
internal/service/user.go:25:15: undefined: UserRepository
internal/handler/api.go:42:9: cannot use x (type string) as type int
internal/handler/api.go:58:2: missing return at end of function
```
Errors found: 3
## Fix 1: Undefined Identifier
File: internal/service/user.go:25
Error: undefined: UserRepository
Cause: Missing import
```go
// Added import
import "project/internal/repository"
// Changed
var repo UserRepository
// To
var repo repository.UserRepository
```
```bash
$ go build ./...
# 2 errors remaining
```
## Fix 2: Type Mismatch
File: internal/handler/api.go:42
Error: cannot use x (type string) as type int
```go
// Changed
count := params.Get("count")
// To
countStr := params.Get("count")
count, _ := strconv.Atoi(countStr)
```
```bash
$ go build ./...
# 1 error remaining
```
## Fix 3: Missing Return
File: internal/handler/api.go:58
Error: missing return at end of function
```go
func GetUser(id string) (*User, error) {
if id == "" {
return nil, ErrInvalidID
}
user := findUser(id)
// Added missing return
return user, nil
}
```
```bash
$ go build ./...
# Build successful!
```
## Final Verification
```bash
$ go vet ./...
# No issues
$ go test ./...
ok project/internal/service 0.015s
ok project/internal/handler 0.023s
```
## Summary
| Metric | Count |
|--------|-------|
| Build errors fixed | 3 |
| Vet warnings fixed | 0 |
| Files modified | 2 |
| Remaining issues | 0 |
Build Status: ✅ SUCCESS
```
## Common Errors Fixed
| Error | Typical Fix |
|-------|-------------|
| `undefined: X` | Add import or fix typo |
| `cannot use X as Y` | Type conversion or fix assignment |
| `missing return` | Add return statement |
| `X does not implement Y` | Add missing method |
| `import cycle` | Restructure packages |
| `declared but not used` | Remove or use variable |
| `cannot find package` | `go get` or `go mod tidy` |
## Fix Strategy
1. **Build errors first** - Code must compile
2. **Vet warnings second** - Fix suspicious constructs
3. **Lint warnings third** - Style and best practices
4. **One fix at a time** - Verify each change
5. **Minimal changes** - Don't refactor, just fix
## Stop Conditions
The agent will stop and report if:
- Same error persists after 3 attempts
- Fix introduces more errors
- Requires architectural changes
- Missing external dependencies
## Related Commands
- `/go-test` - Run tests after build succeeds
- `/go-review` - Review code quality
- `/verify` - Full verification loop
## Related
- Agent: `agents/go-build-resolver.md`
- Skill: `skills/golang-patterns/`

148
commands/go-review.md Normal file
View File

@@ -0,0 +1,148 @@
---
description: Comprehensive Go code review for idiomatic patterns, concurrency safety, error handling, and security. Invokes the go-reviewer agent.
---
# Go Code Review
This command invokes the **go-reviewer** agent for comprehensive Go-specific code review.
## What This Command Does
1. **Identify Go Changes**: Find modified `.go` files via `git diff`
2. **Run Static Analysis**: Execute `go vet`, `staticcheck`, and `golangci-lint`
3. **Security Scan**: Check for SQL injection, command injection, race conditions
4. **Concurrency Review**: Analyze goroutine safety, channel usage, mutex patterns
5. **Idiomatic Go Check**: Verify code follows Go conventions and best practices
6. **Generate Report**: Categorize issues by severity
## When to Use
Use `/go-review` when:
- After writing or modifying Go code
- Before committing Go changes
- Reviewing pull requests with Go code
- Onboarding to a new Go codebase
- Learning idiomatic Go patterns
## Review Categories
### CRITICAL (Must Fix)
- SQL/Command injection vulnerabilities
- Race conditions without synchronization
- Goroutine leaks
- Hardcoded credentials
- Unsafe pointer usage
- Ignored errors in critical paths
### HIGH (Should Fix)
- Missing error wrapping with context
- Panic instead of error returns
- Context not propagated
- Unbuffered channels causing deadlocks
- Interface not satisfied errors
- Missing mutex protection
### MEDIUM (Consider)
- Non-idiomatic code patterns
- Missing godoc comments on exports
- Inefficient string concatenation
- Slice not preallocated
- Table-driven tests not used
## Automated Checks Run
```bash
# Static analysis
go vet ./...
# Advanced checks (if installed)
staticcheck ./...
golangci-lint run
# Race detection
go build -race ./...
# Security vulnerabilities
govulncheck ./...
```
## Example Usage
```text
User: /go-review
Agent:
# Go Code Review Report
## Files Reviewed
- internal/handler/user.go (modified)
- internal/service/auth.go (modified)
## Static Analysis Results
✓ go vet: No issues
✓ staticcheck: No issues
## Issues Found
[CRITICAL] Race Condition
File: internal/service/auth.go:45
Issue: Shared map accessed without synchronization
```go
var cache = map[string]*Session{} // Concurrent access!
func GetSession(id string) *Session {
return cache[id] // Race condition
}
```
Fix: Use sync.RWMutex or sync.Map
```go
var (
cache = map[string]*Session{}
cacheMu sync.RWMutex
)
func GetSession(id string) *Session {
cacheMu.RLock()
defer cacheMu.RUnlock()
return cache[id]
}
```
[HIGH] Missing Error Context
File: internal/handler/user.go:28
Issue: Error returned without context
```go
return err // No context
```
Fix: Wrap with context
```go
return fmt.Errorf("get user %s: %w", userID, err)
```
## Summary
- CRITICAL: 1
- HIGH: 1
- MEDIUM: 0
Recommendation: ❌ Block merge until CRITICAL issue is fixed
```
## Approval Criteria
| Status | Condition |
|--------|-----------|
| ✅ Approve | No CRITICAL or HIGH issues |
| ⚠️ Warning | Only MEDIUM issues (merge with caution) |
| ❌ Block | CRITICAL or HIGH issues found |
## Integration with Other Commands
- Use `/go-test` first to ensure tests pass
- Use `/go-build` if build errors occur
- Use `/go-review` before committing
- Use `/code-review` for non-Go specific concerns
## Related
- Agent: `agents/go-reviewer.md`
- Skills: `skills/golang-patterns/`, `skills/golang-testing/`

268
commands/go-test.md Normal file
View File

@@ -0,0 +1,268 @@
---
description: Enforce TDD workflow for Go. Write table-driven tests first, then implement. Verify 80%+ coverage with go test -cover.
---
# Go TDD Command
This command enforces test-driven development methodology for Go code using idiomatic Go testing patterns.
## What This Command Does
1. **Define Types/Interfaces**: Scaffold function signatures first
2. **Write Table-Driven Tests**: Create comprehensive test cases (RED)
3. **Run Tests**: Verify tests fail for the right reason
4. **Implement Code**: Write minimal code to pass (GREEN)
5. **Refactor**: Improve while keeping tests green
6. **Check Coverage**: Ensure 80%+ coverage
## When to Use
Use `/go-test` when:
- Implementing new Go functions
- Adding test coverage to existing code
- Fixing bugs (write failing test first)
- Building critical business logic
- Learning TDD workflow in Go
## TDD Cycle
```
RED → Write failing table-driven test
GREEN → Implement minimal code to pass
REFACTOR → Improve code, tests stay green
REPEAT → Next test case
```
## Example Session
````
User: /go-test I need a function to validate email addresses
Agent:
# TDD Session: Email Validator
## Step 1: Define Interface
```go
// validator/email.go
package validator
// ValidateEmail checks if the given string is a valid email address.
// Returns nil if valid, error describing the issue otherwise.
func ValidateEmail(email string) error {
panic("not implemented")
}
```
## Step 2: Write Table-Driven Tests (RED)
```go
// validator/email_test.go
package validator
import (
"testing"
)
func TestValidateEmail(t *testing.T) {
tests := []struct {
name string
email string
wantErr bool
}{
// Valid emails
{"simple email", "user@example.com", false},
{"with subdomain", "user@mail.example.com", false},
{"with plus", "user+tag@example.com", false},
{"with dots", "first.last@example.com", false},
// Invalid emails
{"empty string", "", true},
{"no at sign", "userexample.com", true},
{"no domain", "user@", true},
{"no local part", "@example.com", true},
{"double at", "user@@example.com", true},
{"spaces", "user @example.com", true},
{"no tld", "user@example", true},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
err := ValidateEmail(tt.email)
if tt.wantErr && err == nil {
t.Errorf("ValidateEmail(%q) = nil; want error", tt.email)
}
if !tt.wantErr && err != nil {
t.Errorf("ValidateEmail(%q) = %v; want nil", tt.email, err)
}
})
}
}
```
## Step 3: Run Tests - Verify FAIL
```bash
$ go test ./validator/...
--- FAIL: TestValidateEmail (0.00s)
--- FAIL: TestValidateEmail/simple_email (0.00s)
panic: not implemented
FAIL
```
✓ Tests fail as expected (panic).
## Step 4: Implement Minimal Code (GREEN)
```go
// validator/email.go
package validator
import (
"errors"
"regexp"
)
var emailRegex = regexp.MustCompile(`^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$`)
var (
ErrEmailEmpty = errors.New("email cannot be empty")
ErrEmailInvalid = errors.New("email format is invalid")
)
func ValidateEmail(email string) error {
if email == "" {
return ErrEmailEmpty
}
if !emailRegex.MatchString(email) {
return ErrEmailInvalid
}
return nil
}
```
## Step 5: Run Tests - Verify PASS
```bash
$ go test ./validator/...
PASS
ok project/validator 0.003s
```
✓ All tests passing!
## Step 6: Check Coverage
```bash
$ go test -cover ./validator/...
PASS
coverage: 100.0% of statements
ok project/validator 0.003s
```
✓ Coverage: 100%
## TDD Complete!
````
## Test Patterns
### Table-Driven Tests
```go
tests := []struct {
name string
input InputType
want OutputType
wantErr bool
}{
{"case 1", input1, want1, false},
{"case 2", input2, want2, true},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
got, err := Function(tt.input)
// assertions
})
}
```
### Parallel Tests
```go
for _, tt := range tests {
tt := tt // Capture
t.Run(tt.name, func(t *testing.T) {
t.Parallel()
// test body
})
}
```
### Test Helpers
```go
func setupTestDB(t *testing.T) *sql.DB {
t.Helper()
db := createDB()
t.Cleanup(func() { db.Close() })
return db
}
```
## Coverage Commands
```bash
# Basic coverage
go test -cover ./...
# Coverage profile
go test -coverprofile=coverage.out ./...
# View in browser
go tool cover -html=coverage.out
# Coverage by function
go tool cover -func=coverage.out
# With race detection
go test -race -cover ./...
```
## Coverage Targets
| Code Type | Target |
|-----------|--------|
| Critical business logic | 100% |
| Public APIs | 90%+ |
| General code | 80%+ |
| Generated code | Exclude |
## TDD Best Practices
**DO:**
- Write test FIRST, before any implementation
- Run tests after each change
- Use table-driven tests for comprehensive coverage
- Test behavior, not implementation details
- Include edge cases (empty, nil, max values)
**DON'T:**
- Write implementation before tests
- Skip the RED phase
- Test private functions directly
- Use `time.Sleep` in tests
- Ignore flaky tests
## Related Commands
- `/go-build` - Fix build errors
- `/go-review` - Review code after implementation
- `/verify` - Run full verification loop
## Related
- Skill: `skills/golang-testing/`
- Skill: `skills/tdd-workflow/`

70
commands/learn.md Normal file
View File

@@ -0,0 +1,70 @@
# /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 file at `~/.claude/skills/learned/[pattern-name].md`:
```markdown
# [Descriptive Pattern Name]
**Extracted:** [Date]
**Context:** [Brief description of when this applies]
## Problem
[What problem this solves - be specific]
## Solution
[The pattern/technique/workaround]
## Example
[Code example if applicable]
## When to Use
[Trigger conditions - what should activate this skill]
```
## Process
1. Review the session for extractable patterns
2. Identify the most valuable/reusable insight
3. Draft the skill file
4. Ask user to confirm before saving
5. Save to `~/.claude/skills/learned/`
## 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

158
commands/multi-backend.md Normal file
View File

@@ -0,0 +1,158 @@
# Backend - Backend-Focused Development
Backend-focused workflow (Research → Ideation → Plan → Execute → Optimize → Review), Codex-led.
## Usage
```bash
/backend <backend task description>
```
## Context
- Backend task: $ARGUMENTS
- Codex-led, Gemini for auxiliary reference
- Applicable: API design, algorithm implementation, database optimization, business logic
## Your Role
You are the **Backend Orchestrator**, coordinating multi-model collaboration for server-side tasks (Research → Ideation → Plan → Execute → Optimize → Review).
**Collaborative Models**:
- **Codex** – Backend logic, algorithms (**Backend authority, trustworthy**)
- **Gemini** – Frontend perspective (**Backend opinions for reference only**)
- **Claude (self)** – Orchestration, planning, execution, delivery
---
## Multi-Model Call Specification
**Call Syntax**:
```
# New session call
Bash({
command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend codex - \"$PWD\" <<'EOF'
ROLE_FILE: <role prompt path>
<TASK>
Requirement: <enhanced requirement (or $ARGUMENTS if not enhanced)>
Context: <project context and analysis from previous phases>
</TASK>
OUTPUT: Expected output format
EOF",
run_in_background: false,
timeout: 3600000,
description: "Brief description"
})
# Resume session call
Bash({
command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend codex resume <SESSION_ID> - \"$PWD\" <<'EOF'
ROLE_FILE: <role prompt path>
<TASK>
Requirement: <enhanced requirement (or $ARGUMENTS if not enhanced)>
Context: <project context and analysis from previous phases>
</TASK>
OUTPUT: Expected output format
EOF",
run_in_background: false,
timeout: 3600000,
description: "Brief description"
})
```
**Role Prompts**:
| Phase | Codex |
|-------|-------|
| Analysis | `~/.claude/.ccg/prompts/codex/analyzer.md` |
| Planning | `~/.claude/.ccg/prompts/codex/architect.md` |
| Review | `~/.claude/.ccg/prompts/codex/reviewer.md` |
**Session Reuse**: Each call returns `SESSION_ID: xxx`, use `resume xxx` for subsequent phases. Save `CODEX_SESSION` in Phase 2, use `resume` in Phases 3 and 5.
---
## Communication Guidelines
1. Start responses with mode label `[Mode: X]`, initial is `[Mode: Research]`
2. Follow strict sequence: `Research → Ideation → Plan → Execute → Optimize → Review`
3. Use `AskUserQuestion` tool for user interaction when needed (e.g., confirmation/selection/approval)
---
## Core Workflow
### Phase 0: Prompt Enhancement (Optional)
`[Mode: Prepare]` - If ace-tool MCP available, call `mcp__ace-tool__enhance_prompt`, **replace original $ARGUMENTS with enhanced result for subsequent Codex calls**
### Phase 1: Research
`[Mode: Research]` - Understand requirements and gather context
1. **Code Retrieval** (if ace-tool MCP available): Call `mcp__ace-tool__search_context` to retrieve existing APIs, data models, service architecture
2. Requirement completeness score (0-10): >=7 continue, <7 stop and supplement
### Phase 2: Ideation
`[Mode: Ideation]` - Codex-led analysis
**MUST call Codex** (follow call specification above):
- ROLE_FILE: `~/.claude/.ccg/prompts/codex/analyzer.md`
- Requirement: Enhanced requirement (or $ARGUMENTS if not enhanced)
- Context: Project context from Phase 1
- OUTPUT: Technical feasibility analysis, recommended solutions (at least 2), risk assessment
**Save SESSION_ID** (`CODEX_SESSION`) for subsequent phase reuse.
Output solutions (at least 2), wait for user selection.
### Phase 3: Planning
`[Mode: Plan]` - Codex-led planning
**MUST call Codex** (use `resume <CODEX_SESSION>` to reuse session):
- ROLE_FILE: `~/.claude/.ccg/prompts/codex/architect.md`
- Requirement: User's selected solution
- Context: Analysis results from Phase 2
- OUTPUT: File structure, function/class design, dependency relationships
Claude synthesizes plan, save to `.claude/plan/task-name.md` after user approval.
### Phase 4: Implementation
`[Mode: Execute]` - Code development
- Strictly follow approved plan
- Follow existing project code standards
- Ensure error handling, security, performance optimization
### Phase 5: Optimization
`[Mode: Optimize]` - Codex-led review
**MUST call Codex** (follow call specification above):
- ROLE_FILE: `~/.claude/.ccg/prompts/codex/reviewer.md`
- Requirement: Review the following backend code changes
- Context: git diff or code content
- OUTPUT: Security, performance, error handling, API compliance issues list
Integrate review feedback, execute optimization after user confirmation.
### Phase 6: Quality Review
`[Mode: Review]` - Final evaluation
- Check completion against plan
- Run tests to verify functionality
- Report issues and recommendations
---
## Key Rules
1. **Codex backend opinions are trustworthy**
2. **Gemini backend opinions for reference only**
3. External models have **zero filesystem write access**
4. Claude handles all code writes and file operations

310
commands/multi-execute.md Normal file
View File

@@ -0,0 +1,310 @@
# 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]`
**Must use MCP tool for quick context retrieval, do NOT manually read files one by one**
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
- **NEVER** use Bash + find/ls to manually explore project structure
**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

158
commands/multi-frontend.md Normal file
View File

@@ -0,0 +1,158 @@
# Frontend - Frontend-Focused Development
Frontend-focused workflow (Research → Ideation → Plan → Execute → Optimize → Review), Gemini-led.
## Usage
```bash
/frontend <UI task description>
```
## Context
- Frontend task: $ARGUMENTS
- Gemini-led, Codex for auxiliary reference
- Applicable: Component design, responsive layout, UI animations, style optimization
## Your Role
You are the **Frontend Orchestrator**, coordinating multi-model collaboration for UI/UX tasks (Research → Ideation → Plan → Execute → Optimize → Review).
**Collaborative Models**:
- **Gemini** – Frontend UI/UX (**Frontend authority, trustworthy**)
- **Codex** – Backend perspective (**Frontend opinions for reference only**)
- **Claude (self)** – Orchestration, planning, execution, delivery
---
## Multi-Model Call Specification
**Call Syntax**:
```
# New session call
Bash({
command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend gemini --gemini-model gemini-3-pro-preview - \"$PWD\" <<'EOF'
ROLE_FILE: <role prompt path>
<TASK>
Requirement: <enhanced requirement (or $ARGUMENTS if not enhanced)>
Context: <project context and analysis from previous phases>
</TASK>
OUTPUT: Expected output format
EOF",
run_in_background: false,
timeout: 3600000,
description: "Brief description"
})
# Resume session call
Bash({
command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend gemini --gemini-model gemini-3-pro-preview resume <SESSION_ID> - \"$PWD\" <<'EOF'
ROLE_FILE: <role prompt path>
<TASK>
Requirement: <enhanced requirement (or $ARGUMENTS if not enhanced)>
Context: <project context and analysis from previous phases>
</TASK>
OUTPUT: Expected output format
EOF",
run_in_background: false,
timeout: 3600000,
description: "Brief description"
})
```
**Role Prompts**:
| Phase | Gemini |
|-------|--------|
| Analysis | `~/.claude/.ccg/prompts/gemini/analyzer.md` |
| Planning | `~/.claude/.ccg/prompts/gemini/architect.md` |
| Review | `~/.claude/.ccg/prompts/gemini/reviewer.md` |
**Session Reuse**: Each call returns `SESSION_ID: xxx`, use `resume xxx` for subsequent phases. Save `GEMINI_SESSION` in Phase 2, use `resume` in Phases 3 and 5.
---
## Communication Guidelines
1. Start responses with mode label `[Mode: X]`, initial is `[Mode: Research]`
2. Follow strict sequence: `Research → Ideation → Plan → Execute → Optimize → Review`
3. Use `AskUserQuestion` tool for user interaction when needed (e.g., confirmation/selection/approval)
---
## Core Workflow
### Phase 0: Prompt Enhancement (Optional)
`[Mode: Prepare]` - If ace-tool MCP available, call `mcp__ace-tool__enhance_prompt`, **replace original $ARGUMENTS with enhanced result for subsequent Gemini calls**
### Phase 1: Research
`[Mode: Research]` - Understand requirements and gather context
1. **Code Retrieval** (if ace-tool MCP available): Call `mcp__ace-tool__search_context` to retrieve existing components, styles, design system
2. Requirement completeness score (0-10): >=7 continue, <7 stop and supplement
### Phase 2: Ideation
`[Mode: Ideation]` - Gemini-led analysis
**MUST call Gemini** (follow call specification above):
- ROLE_FILE: `~/.claude/.ccg/prompts/gemini/analyzer.md`
- Requirement: Enhanced requirement (or $ARGUMENTS if not enhanced)
- Context: Project context from Phase 1
- OUTPUT: UI feasibility analysis, recommended solutions (at least 2), UX evaluation
**Save SESSION_ID** (`GEMINI_SESSION`) for subsequent phase reuse.
Output solutions (at least 2), wait for user selection.
### Phase 3: Planning
`[Mode: Plan]` - Gemini-led planning
**MUST call Gemini** (use `resume <GEMINI_SESSION>` to reuse session):
- ROLE_FILE: `~/.claude/.ccg/prompts/gemini/architect.md`
- Requirement: User's selected solution
- Context: Analysis results from Phase 2
- OUTPUT: Component structure, UI flow, styling approach
Claude synthesizes plan, save to `.claude/plan/task-name.md` after user approval.
### Phase 4: Implementation
`[Mode: Execute]` - Code development
- Strictly follow approved plan
- Follow existing project design system and code standards
- Ensure responsiveness, accessibility
### Phase 5: Optimization
`[Mode: Optimize]` - Gemini-led review
**MUST call Gemini** (follow call specification above):
- ROLE_FILE: `~/.claude/.ccg/prompts/gemini/reviewer.md`
- Requirement: Review the following frontend code changes
- Context: git diff or code content
- OUTPUT: Accessibility, responsiveness, performance, design consistency issues list
Integrate review feedback, execute optimization after user confirmation.
### Phase 6: Quality Review
`[Mode: Review]` - Final evaluation
- Check completion against plan
- Verify responsiveness and accessibility
- Report issues and recommendations
---
## Key Rules
1. **Gemini frontend opinions are trustworthy**
2. **Codex frontend opinions for reference only**
3. External models have **zero filesystem write access**
4. Claude handles all code writes and file operations

261
commands/multi-plan.md Normal file
View File

@@ -0,0 +1,261 @@
# Plan - Multi-Model Collaborative Planning
Multi-model collaborative planning - Context retrieval + Dual-model analysis → Generate step-by-step implementation plan.
$ARGUMENTS
---
## Core Protocols
- **Language Protocol**: Use **English** when interacting with tools/models, communicate with user in their language
- **Mandatory Parallel**: Codex/Gemini calls MUST use `run_in_background: true` (including single model calls, to avoid blocking main thread)
- **Code Sovereignty**: External models have **zero filesystem write access**, all modifications by Claude
- **Stop-Loss Mechanism**: Do not proceed to next phase until current phase output is validated
- **Planning Only**: This command allows reading context and writing to `.claude/plan/*` plan files, but **NEVER modify production code**
---
## Multi-Model Call Specification
**Call Syntax** (parallel: use `run_in_background: true`):
```
Bash({
command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend <codex|gemini> {{GEMINI_MODEL_FLAG}}- \"$PWD\" <<'EOF'
ROLE_FILE: <role prompt path>
<TASK>
Requirement: <enhanced requirement>
Context: <retrieved project context>
</TASK>
OUTPUT: Step-by-step implementation plan with pseudo-code. DO NOT modify any files.
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 |
|-------|-------|--------|
| Analysis | `~/.claude/.ccg/prompts/codex/analyzer.md` | `~/.claude/.ccg/prompts/gemini/analyzer.md` |
| Planning | `~/.claude/.ccg/prompts/codex/architect.md` | `~/.claude/.ccg/prompts/gemini/architect.md` |
**Session Reuse**: Each call returns `SESSION_ID: xxx` (typically output by wrapper), **MUST save** for subsequent `/ccg:execute` use.
**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
**Planning Task**: $ARGUMENTS
### Phase 1: Full Context Retrieval
`[Mode: Research]`
#### 1.1 Prompt Enhancement (MUST execute first)
**MUST call `mcp__ace-tool__enhance_prompt` tool**:
```
mcp__ace-tool__enhance_prompt({
prompt: "$ARGUMENTS",
conversation_history: "<last 5-10 conversation turns>",
project_root_path: "$PWD"
})
```
Wait for enhanced prompt, **replace original $ARGUMENTS with enhanced result** for all subsequent phases.
#### 1.2 Context Retrieval
**Call `mcp__ace-tool__search_context` tool**:
```
mcp__ace-tool__search_context({
query: "<semantic query based on enhanced requirement>",
project_root_path: "$PWD"
})
```
- Build semantic query using natural language (Where/What/How)
- **NEVER answer based on assumptions**
- If MCP unavailable: fallback to Glob + Grep for file discovery and key symbol location
#### 1.3 Completeness Check
- Must obtain **complete definitions and signatures** for relevant classes, functions, variables
- If context insufficient, trigger **recursive retrieval**
- Prioritize output: entry file + line number + key symbol name; add minimal code snippets only when necessary to resolve ambiguity
#### 1.4 Requirement Alignment
- If requirements still have ambiguity, **MUST** output guiding questions for user
- Until requirement boundaries are clear (no omissions, no redundancy)
### Phase 2: Multi-Model Collaborative Analysis
`[Mode: Analysis]`
#### 2.1 Distribute Inputs
**Parallel call** Codex and Gemini (`run_in_background: true`):
Distribute **original requirement** (without preset opinions) to both models:
1. **Codex Backend Analysis**:
- ROLE_FILE: `~/.claude/.ccg/prompts/codex/analyzer.md`
- Focus: Technical feasibility, architecture impact, performance considerations, potential risks
- OUTPUT: Multi-perspective solutions + pros/cons analysis
2. **Gemini Frontend Analysis**:
- ROLE_FILE: `~/.claude/.ccg/prompts/gemini/analyzer.md`
- Focus: UI/UX impact, user experience, visual design
- OUTPUT: Multi-perspective solutions + pros/cons analysis
Wait for both models' complete results with `TaskOutput`. **Save SESSION_ID** (`CODEX_SESSION` and `GEMINI_SESSION`).
#### 2.2 Cross-Validation
Integrate perspectives and iterate for optimization:
1. **Identify consensus** (strong signal)
2. **Identify divergence** (needs weighing)
3. **Complementary strengths**: Backend logic follows Codex, Frontend design follows Gemini
4. **Logical reasoning**: Eliminate logical gaps in solutions
#### 2.3 (Optional but Recommended) Dual-Model Plan Draft
To reduce risk of omissions in Claude's synthesized plan, can parallel have both models output "plan drafts" (still **NOT allowed** to modify files):
1. **Codex Plan Draft** (Backend authority):
- ROLE_FILE: `~/.claude/.ccg/prompts/codex/architect.md`
- OUTPUT: Step-by-step plan + pseudo-code (focus: data flow/edge cases/error handling/test strategy)
2. **Gemini Plan Draft** (Frontend authority):
- ROLE_FILE: `~/.claude/.ccg/prompts/gemini/architect.md`
- OUTPUT: Step-by-step plan + pseudo-code (focus: information architecture/interaction/accessibility/visual consistency)
Wait for both models' complete results with `TaskOutput`, record key differences in their suggestions.
#### 2.4 Generate Implementation Plan (Claude Final Version)
Synthesize both analyses, generate **Step-by-step Implementation Plan**:
```markdown
## Implementation Plan: <Task Name>
### Task Type
- [ ] Frontend (→ Gemini)
- [ ] Backend (→ Codex)
- [ ] Fullstack (→ Parallel)
### Technical Solution
<Optimal solution synthesized from Codex + Gemini analysis>
### Implementation Steps
1. <Step 1> - Expected deliverable
2. <Step 2> - Expected deliverable
...
### Key Files
| File | Operation | Description |
|------|-----------|-------------|
| path/to/file.ts:L10-L50 | Modify | Description |
### Risks and Mitigation
| Risk | Mitigation |
|------|------------|
### SESSION_ID (for /ccg:execute use)
- CODEX_SESSION: <session_id>
- GEMINI_SESSION: <session_id>
```
### Phase 2 End: Plan Delivery (Not Execution)
**`/ccg:plan` responsibilities end here, MUST execute the following actions**:
1. Present complete implementation plan to user (including pseudo-code)
2. Save plan to `.claude/plan/<feature-name>.md` (extract feature name from requirement, e.g., `user-auth`, `payment-module`)
3. Output prompt in **bold text** (MUST use actual saved file path):
---
**Plan generated and saved to `.claude/plan/actual-feature-name.md`**
**Please review the plan above. You can:**
- **Modify plan**: Tell me what needs adjustment, I'll update the plan
- **Execute plan**: Copy the following command to a new session
```
/ccg:execute .claude/plan/actual-feature-name.md
```
---
**NOTE**: The `actual-feature-name.md` above MUST be replaced with the actual saved filename!
4. **Immediately terminate current response** (Stop here. No more tool calls.)
**ABSOLUTELY FORBIDDEN**:
- Ask user "Y/N" then auto-execute (execution is `/ccg:execute`'s responsibility)
- Any write operations to production code
- Automatically call `/ccg:execute` or any implementation actions
- Continue triggering model calls when user hasn't explicitly requested modifications
---
## Plan Saving
After planning completes, save plan to:
- **First planning**: `.claude/plan/<feature-name>.md`
- **Iteration versions**: `.claude/plan/<feature-name>-v2.md`, `.claude/plan/<feature-name>-v3.md`...
Plan file write should complete before presenting plan to user.
---
## Plan Modification Flow
If user requests plan modifications:
1. Adjust plan content based on user feedback
2. Update `.claude/plan/<feature-name>.md` file
3. Re-present modified plan
4. Prompt user to review or execute again
---
## Next Steps
After user approves, **manually** execute:
```bash
/ccg:execute .claude/plan/<feature-name>.md
```
---
## Key Rules
1. **Plan only, no implementation** – This command does not execute any code changes
2. **No Y/N prompts** – Only present plan, let user decide next steps
3. **Trust Rules** – Backend follows Codex, Frontend follows Gemini
4. External models have **zero filesystem write access**
5. **SESSION_ID Handoff** – Plan must include `CODEX_SESSION` / `GEMINI_SESSION` at end (for `/ccg:execute resume <SESSION_ID>` use)

183
commands/multi-workflow.md Normal file
View File

@@ -0,0 +1,183 @@
# Workflow - Multi-Model Collaborative Development
Multi-model collaborative development workflow (Research → Ideation → Plan → Execute → Optimize → Review), with intelligent routing: Frontend → Gemini, Backend → Codex.
Structured development workflow with quality gates, MCP services, and multi-model collaboration.
## Usage
```bash
/workflow <task description>
```
## Context
- Task to develop: $ARGUMENTS
- Structured 6-phase workflow with quality gates
- Multi-model collaboration: Codex (backend) + Gemini (frontend) + Claude (orchestration)
- MCP service integration (ace-tool) for enhanced capabilities
## Your Role
You are the **Orchestrator**, coordinating a multi-model collaborative system (Research → Ideation → Plan → Execute → Optimize → Review). Communicate concisely and professionally for experienced developers.
**Collaborative Models**:
- **ace-tool MCP** – Code retrieval + Prompt enhancement
- **Codex** – Backend logic, algorithms, debugging (**Backend authority, trustworthy**)
- **Gemini** – Frontend UI/UX, visual design (**Frontend expert, backend opinions for reference only**)
- **Claude (self)** – Orchestration, planning, execution, delivery
---
## Multi-Model Call Specification
**Call syntax** (parallel: `run_in_background: true`, sequential: `false`):
```
# New session call
Bash({
command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend <codex|gemini> {{GEMINI_MODEL_FLAG}}- \"$PWD\" <<'EOF'
ROLE_FILE: <role prompt path>
<TASK>
Requirement: <enhanced requirement (or $ARGUMENTS if not enhanced)>
Context: <project context and analysis from previous phases>
</TASK>
OUTPUT: Expected output format
EOF",
run_in_background: true,
timeout: 3600000,
description: "Brief description"
})
# Resume session call
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: <enhanced requirement (or $ARGUMENTS if not enhanced)>
Context: <project context and analysis from previous phases>
</TASK>
OUTPUT: Expected output format
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 |
|-------|-------|--------|
| Analysis | `~/.claude/.ccg/prompts/codex/analyzer.md` | `~/.claude/.ccg/prompts/gemini/analyzer.md` |
| Planning | `~/.claude/.ccg/prompts/codex/architect.md` | `~/.claude/.ccg/prompts/gemini/architect.md` |
| Review | `~/.claude/.ccg/prompts/codex/reviewer.md` | `~/.claude/.ccg/prompts/gemini/reviewer.md` |
**Session Reuse**: Each call returns `SESSION_ID: xxx`, use `resume xxx` subcommand for subsequent phases (note: `resume`, not `--resume`).
**Parallel Calls**: Use `run_in_background: true` to start, wait for results with `TaskOutput`. **Must wait for all models to return before proceeding to next phase**.
**Wait for Background Tasks** (use 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. Never kill directly.**
---
## Communication Guidelines
1. Start responses with mode label `[Mode: X]`, initial is `[Mode: Research]`.
2. Follow strict sequence: `Research → Ideation → Plan → Execute → Optimize → Review`.
3. Request user confirmation after each phase completion.
4. Force stop when score < 7 or user does not approve.
5. Use `AskUserQuestion` tool for user interaction when needed (e.g., confirmation/selection/approval).
---
## Execution Workflow
**Task Description**: $ARGUMENTS
### Phase 1: Research & Analysis
`[Mode: Research]` - Understand requirements and gather context:
1. **Prompt Enhancement**: Call `mcp__ace-tool__enhance_prompt`, **replace original $ARGUMENTS with enhanced result for all subsequent Codex/Gemini calls**
2. **Context Retrieval**: Call `mcp__ace-tool__search_context`
3. **Requirement Completeness Score** (0-10):
- Goal clarity (0-3), Expected outcome (0-3), Scope boundaries (0-2), Constraints (0-2)
- ≥7: Continue | <7: Stop, ask clarifying questions
### Phase 2: Solution Ideation
`[Mode: Ideation]` - Multi-model parallel analysis:
**Parallel Calls** (`run_in_background: true`):
- Codex: Use analyzer prompt, output technical feasibility, solutions, risks
- Gemini: Use analyzer prompt, output UI feasibility, solutions, UX evaluation
Wait for results with `TaskOutput`. **Save SESSION_ID** (`CODEX_SESSION` and `GEMINI_SESSION`).
**Follow the `IMPORTANT` instructions in `Multi-Model Call Specification` above**
Synthesize both analyses, output solution comparison (at least 2 options), wait for user selection.
### Phase 3: Detailed Planning
`[Mode: Plan]` - Multi-model collaborative planning:
**Parallel Calls** (resume session with `resume <SESSION_ID>`):
- Codex: Use architect prompt + `resume $CODEX_SESSION`, output backend architecture
- Gemini: Use architect prompt + `resume $GEMINI_SESSION`, output frontend architecture
Wait for results with `TaskOutput`.
**Follow the `IMPORTANT` instructions in `Multi-Model Call Specification` above**
**Claude Synthesis**: Adopt Codex backend plan + Gemini frontend plan, save to `.claude/plan/task-name.md` after user approval.
### Phase 4: Implementation
`[Mode: Execute]` - Code development:
- Strictly follow approved plan
- Follow existing project code standards
- Request feedback at key milestones
### Phase 5: Code Optimization
`[Mode: Optimize]` - Multi-model parallel review:
**Parallel Calls**:
- Codex: Use reviewer prompt, focus on security, performance, error handling
- Gemini: Use reviewer prompt, focus on accessibility, design consistency
Wait for results with `TaskOutput`. Integrate review feedback, execute optimization after user confirmation.
**Follow the `IMPORTANT` instructions in `Multi-Model Call Specification` above**
### Phase 6: Quality Review
`[Mode: Review]` - Final evaluation:
- Check completion against plan
- Run tests to verify functionality
- Report issues and recommendations
- Request final user confirmation
---
## Key Rules
1. Phase sequence cannot be skipped (unless user explicitly instructs)
2. External models have **zero filesystem write access**, all modifications by Claude
3. **Force stop** when score < 7 or user does not approve

172
commands/orchestrate.md Normal file
View File

@@ -0,0 +1,172 @@
# Orchestrate Command
Sequential agent workflow for complex tasks.
## Usage
`/orchestrate [workflow-type] [task-description]`
## Workflow Types
### feature
Full feature implementation workflow:
```
planner -> tdd-guide -> code-reviewer -> security-reviewer
```
### bugfix
Bug investigation and fix workflow:
```
planner -> tdd-guide -> code-reviewer
```
### refactor
Safe refactoring workflow:
```
architect -> code-reviewer -> tdd-guide
```
### security
Security-focused review:
```
security-reviewer -> code-reviewer -> architect
```
## Execution Pattern
For each agent in the workflow:
1. **Invoke agent** with context from previous agent
2. **Collect output** as structured handoff document
3. **Pass to next agent** in chain
4. **Aggregate results** into final report
## Handoff Document Format
Between agents, create handoff document:
```markdown
## HANDOFF: [previous-agent] -> [next-agent]
### Context
[Summary of what was done]
### Findings
[Key discoveries or decisions]
### Files Modified
[List of files touched]
### Open Questions
[Unresolved items for next agent]
### Recommendations
[Suggested next steps]
```
## Example: Feature Workflow
```
/orchestrate feature "Add user authentication"
```
Executes:
1. **Planner Agent**
- Analyzes requirements
- Creates implementation plan
- Identifies dependencies
- Output: `HANDOFF: planner -> tdd-guide`
2. **TDD Guide Agent**
- Reads planner handoff
- Writes tests first
- Implements to pass tests
- Output: `HANDOFF: tdd-guide -> code-reviewer`
3. **Code Reviewer Agent**
- Reviews implementation
- Checks for issues
- Suggests improvements
- Output: `HANDOFF: code-reviewer -> security-reviewer`
4. **Security Reviewer Agent**
- Security audit
- Vulnerability check
- Final approval
- Output: Final Report
## Final Report Format
```
ORCHESTRATION REPORT
====================
Workflow: feature
Task: Add user authentication
Agents: planner -> tdd-guide -> code-reviewer -> security-reviewer
SUMMARY
-------
[One paragraph summary]
AGENT OUTPUTS
-------------
Planner: [summary]
TDD Guide: [summary]
Code Reviewer: [summary]
Security Reviewer: [summary]
FILES CHANGED
-------------
[List all files modified]
TEST RESULTS
------------
[Test pass/fail summary]
SECURITY STATUS
---------------
[Security findings]
RECOMMENDATION
--------------
[SHIP / NEEDS WORK / BLOCKED]
```
## Parallel Execution
For independent checks, run agents in parallel:
```markdown
### Parallel Phase
Run simultaneously:
- code-reviewer (quality)
- security-reviewer (security)
- architect (design)
### Merge Results
Combine outputs into single report
```
## Arguments
$ARGUMENTS:
- `feature <description>` - Full feature workflow
- `bugfix <description>` - Bug fix workflow
- `refactor <description>` - Refactoring workflow
- `security <description>` - Security review workflow
- `custom <agents> <description>` - Custom agent sequence
## Custom Workflow Example
```
/orchestrate custom "architect,tdd-guide,code-reviewer" "Redesign caching layer"
```
## Tips
1. **Start with planner** for complex features
2. **Always include code-reviewer** before merge
3. **Use security-reviewer** for auth/payment/PII
4. **Keep handoffs concise** - focus on what next agent needs
5. **Run verification** between agents if needed

113
commands/plan.md Normal file
View File

@@ -0,0 +1,113 @@
---
description: Restate requirements, assess risks, and create step-by-step implementation plan. WAIT for user CONFIRM before touching any code.
---
# Plan Command
This command invokes the **planner** agent to create a comprehensive implementation plan before writing any code.
## What This Command Does
1. **Restate Requirements** - Clarify what needs to be built
2. **Identify Risks** - Surface potential issues and blockers
3. **Create Step Plan** - Break down implementation into phases
4. **Wait for Confirmation** - MUST receive user approval before proceeding
## When to Use
Use `/plan` when:
- Starting a new feature
- Making significant architectural changes
- Working on complex refactoring
- Multiple files/components will be affected
- Requirements are unclear or ambiguous
## How It Works
The planner agent will:
1. **Analyze the request** and restate requirements in clear terms
2. **Break down into phases** with specific, actionable steps
3. **Identify dependencies** between components
4. **Assess risks** and potential blockers
5. **Estimate complexity** (High/Medium/Low)
6. **Present the plan** and WAIT for your explicit confirmation
## Example Usage
```
User: /plan I need to add real-time notifications when markets resolve
Agent (planner):
# Implementation Plan: Real-Time Market Resolution Notifications
## Requirements Restatement
- Send notifications to users when markets they're watching resolve
- Support multiple notification channels (in-app, email, webhook)
- Ensure notifications are delivered reliably
- Include market outcome and user's position result
## Implementation Phases
### Phase 1: Database Schema
- Add notifications table with columns: id, user_id, market_id, type, status, created_at
- Add user_notification_preferences table for channel preferences
- Create indexes on user_id and market_id for performance
### Phase 2: Notification Service
- Create notification service in lib/notifications.ts
- Implement notification queue using BullMQ/Redis
- Add retry logic for failed deliveries
- Create notification templates
### Phase 3: Integration Points
- Hook into market resolution logic (when status changes to "resolved")
- Query all users with positions in market
- Enqueue notifications for each user
### Phase 4: Frontend Components
- Create NotificationBell component in header
- Add NotificationList modal
- Implement real-time updates via Supabase subscriptions
- Add notification preferences page
## Dependencies
- Redis (for queue)
- Email service (SendGrid/Resend)
- Supabase real-time subscriptions
## Risks
- HIGH: Email deliverability (SPF/DKIM required)
- MEDIUM: Performance with 1000+ users per market
- MEDIUM: Notification spam if markets resolve frequently
- LOW: Real-time subscription overhead
## Estimated Complexity: MEDIUM
- Backend: 4-6 hours
- Frontend: 3-4 hours
- Testing: 2-3 hours
- Total: 9-13 hours
**WAITING FOR CONFIRMATION**: Proceed with this plan? (yes/no/modify)
```
## Important Notes
**CRITICAL**: The planner agent will **NOT** write any code until you explicitly confirm the plan with "yes" or "proceed" or similar affirmative response.
If you want changes, respond with:
- "modify: [your changes]"
- "different approach: [alternative]"
- "skip phase 2 and do phase 3 first"
## Integration with Other Commands
After planning:
- Use `/tdd` to implement with test-driven development
- Use `/build-fix` if build errors occur
- Use `/code-review` to review completed implementation
## Related Agents
This command invokes the `planner` agent located at:
`~/.claude/agents/planner.md`

272
commands/pm2.md Normal file
View File

@@ -0,0 +1,272 @@
# PM2 Init
Auto-analyze project and generate PM2 service commands.
**Command**: `$ARGUMENTS`
---
## Workflow
1. Check PM2 (install via `npm install -g pm2` if missing)
2. Scan project to identify services (frontend/backend/database)
3. Generate config files and individual command files
---
## Service Detection
| Type | Detection | Default Port |
|------|-----------|--------------|
| Vite | vite.config.* | 5173 |
| Next.js | next.config.* | 3000 |
| Nuxt | nuxt.config.* | 3000 |
| CRA | react-scripts in package.json | 3000 |
| Express/Node | server/backend/api directory + package.json | 3000 |
| FastAPI/Flask | requirements.txt / pyproject.toml | 8000 |
| Go | go.mod / main.go | 8080 |
**Port Detection Priority**: User specified > .env > config file > scripts args > default port
---
## Generated Files
```
project/
├── ecosystem.config.cjs # PM2 config
├── {backend}/start.cjs # Python wrapper (if applicable)
└── .claude/
├── commands/
│ ├── pm2-all.md # Start all + monit
│ ├── pm2-all-stop.md # Stop all
│ ├── pm2-all-restart.md # Restart all
│ ├── pm2-{port}.md # Start single + logs
│ ├── pm2-{port}-stop.md # Stop single
│ ├── pm2-{port}-restart.md # Restart single
│ ├── pm2-logs.md # View all logs
│ └── pm2-status.md # View status
└── scripts/
├── pm2-logs-{port}.ps1 # Single service logs
└── pm2-monit.ps1 # PM2 monitor
```
---
## Windows Configuration (IMPORTANT)
### ecosystem.config.cjs
**Must use `.cjs` extension**
```javascript
module.exports = {
apps: [
// Node.js (Vite/Next/Nuxt)
{
name: 'project-3000',
cwd: './packages/web',
script: 'node_modules/vite/bin/vite.js',
args: '--port 3000',
interpreter: 'C:/Program Files/nodejs/node.exe',
env: { NODE_ENV: 'development' }
},
// Python
{
name: 'project-8000',
cwd: './backend',
script: 'start.cjs',
interpreter: 'C:/Program Files/nodejs/node.exe',
env: { PYTHONUNBUFFERED: '1' }
}
]
}
```
**Framework script paths:**
| Framework | script | args |
|-----------|--------|------|
| Vite | `node_modules/vite/bin/vite.js` | `--port {port}` |
| Next.js | `node_modules/next/dist/bin/next` | `dev -p {port}` |
| Nuxt | `node_modules/nuxt/bin/nuxt.mjs` | `dev --port {port}` |
| Express | `src/index.js` or `server.js` | - |
### Python Wrapper Script (start.cjs)
```javascript
const { spawn } = require('child_process');
const proc = spawn('python', ['-m', 'uvicorn', 'app.main:app', '--host', '0.0.0.0', '--port', '8000', '--reload'], {
cwd: __dirname, stdio: 'inherit', windowsHide: true
});
proc.on('close', (code) => process.exit(code));
```
---
## Command File Templates (Minimal Content)
### pm2-all.md (Start all + monit)
````markdown
Start all services and open PM2 monitor.
```bash
cd "{PROJECT_ROOT}" && pm2 start ecosystem.config.cjs && start wt.exe -d "{PROJECT_ROOT}" pwsh -NoExit -c "pm2 monit"
```
````
### pm2-all-stop.md
````markdown
Stop all services.
```bash
cd "{PROJECT_ROOT}" && pm2 stop all
```
````
### pm2-all-restart.md
````markdown
Restart all services.
```bash
cd "{PROJECT_ROOT}" && pm2 restart all
```
````
### pm2-{port}.md (Start single + logs)
````markdown
Start {name} ({port}) and open logs.
```bash
cd "{PROJECT_ROOT}" && pm2 start ecosystem.config.cjs --only {name} && start wt.exe -d "{PROJECT_ROOT}" pwsh -NoExit -c "pm2 logs {name}"
```
````
### pm2-{port}-stop.md
````markdown
Stop {name} ({port}).
```bash
cd "{PROJECT_ROOT}" && pm2 stop {name}
```
````
### pm2-{port}-restart.md
````markdown
Restart {name} ({port}).
```bash
cd "{PROJECT_ROOT}" && pm2 restart {name}
```
````
### pm2-logs.md
````markdown
View all PM2 logs.
```bash
cd "{PROJECT_ROOT}" && pm2 logs
```
````
### pm2-status.md
````markdown
View PM2 status.
```bash
cd "{PROJECT_ROOT}" && pm2 status
```
````
### PowerShell Scripts (pm2-logs-{port}.ps1)
```powershell
Set-Location "{PROJECT_ROOT}"
pm2 logs {name}
```
### PowerShell Scripts (pm2-monit.ps1)
```powershell
Set-Location "{PROJECT_ROOT}"
pm2 monit
```
---
## Key Rules
1. **Config file**: `ecosystem.config.cjs` (not .js)
2. **Node.js**: Specify bin path directly + interpreter
3. **Python**: Node.js wrapper script + `windowsHide: true`
4. **Open new window**: `start wt.exe -d "{path}" pwsh -NoExit -c "command"`
5. **Minimal content**: Each command file has only 1-2 lines description + bash block
6. **Direct execution**: No AI parsing needed, just run the bash command
---
## Execute
Based on `$ARGUMENTS`, execute init:
1. Scan project for services
2. Generate `ecosystem.config.cjs`
3. Generate `{backend}/start.cjs` for Python services (if applicable)
4. Generate command files in `.claude/commands/`
5. Generate script files in `.claude/scripts/`
6. **Update project CLAUDE.md** with PM2 info (see below)
7. **Display completion summary** with terminal commands
---
## Post-Init: Update CLAUDE.md
After generating files, append PM2 section to project's `CLAUDE.md` (create if not exists):
````markdown
## PM2 Services
| Port | Name | Type |
|------|------|------|
| {port} | {name} | {type} |
**Terminal Commands:**
```bash
pm2 start ecosystem.config.cjs # First time
pm2 start all # After first time
pm2 stop all / pm2 restart all
pm2 start {name} / pm2 stop {name}
pm2 logs / pm2 status / pm2 monit
pm2 save # Save process list
pm2 resurrect # Restore saved list
```
````
**Rules for CLAUDE.md update:**
- If PM2 section exists, replace it
- If not exists, append to end
- Keep content minimal and essential
---
## Post-Init: Display Summary
After all files generated, output:
```
## PM2 Init Complete
**Services:**
| Port | Name | Type |
|------|------|------|
| {port} | {name} | {type} |
**Claude Commands:** /pm2-all, /pm2-all-stop, /pm2-{port}, /pm2-{port}-stop, /pm2-logs, /pm2-status
**Terminal Commands:**
## First time (with config file)
pm2 start ecosystem.config.cjs && pm2 save
## After first time (simplified)
pm2 start all # Start all
pm2 stop all # Stop all
pm2 restart all # Restart all
pm2 start {name} # Start single
pm2 stop {name} # Stop single
pm2 logs # View logs
pm2 monit # Monitor panel
pm2 resurrect # Restore saved processes
**Tip:** Run `pm2 save` after first start to enable simplified commands.
```

297
commands/python-review.md Normal file
View File

@@ -0,0 +1,297 @@
---
description: Comprehensive Python code review for PEP 8 compliance, type hints, security, and Pythonic idioms. Invokes the python-reviewer agent.
---
# Python Code Review
This command invokes the **python-reviewer** agent for comprehensive Python-specific code review.
## What This Command Does
1. **Identify Python Changes**: Find modified `.py` files via `git diff`
2. **Run Static Analysis**: Execute `ruff`, `mypy`, `pylint`, `black --check`
3. **Security Scan**: Check for SQL injection, command injection, unsafe deserialization
4. **Type Safety Review**: Analyze type hints and mypy errors
5. **Pythonic Code Check**: Verify code follows PEP 8 and Python best practices
6. **Generate Report**: Categorize issues by severity
## When to Use
Use `/python-review` when:
- After writing or modifying Python code
- Before committing Python changes
- Reviewing pull requests with Python code
- Onboarding to a new Python codebase
- Learning Pythonic patterns and idioms
## Review Categories
### CRITICAL (Must Fix)
- SQL/Command injection vulnerabilities
- Unsafe eval/exec usage
- Pickle unsafe deserialization
- Hardcoded credentials
- YAML unsafe load
- Bare except clauses hiding errors
### HIGH (Should Fix)
- Missing type hints on public functions
- Mutable default arguments
- Swallowing exceptions silently
- Not using context managers for resources
- C-style looping instead of comprehensions
- Using type() instead of isinstance()
- Race conditions without locks
### MEDIUM (Consider)
- PEP 8 formatting violations
- Missing docstrings on public functions
- Print statements instead of logging
- Inefficient string operations
- Magic numbers without named constants
- Not using f-strings for formatting
- Unnecessary list creation
## Automated Checks Run
```bash
# Type checking
mypy .
# Linting and formatting
ruff check .
black --check .
isort --check-only .
# Security scanning
bandit -r .
# Dependency audit
pip-audit
safety check
# Testing
pytest --cov=app --cov-report=term-missing
```
## Example Usage
```text
User: /python-review
Agent:
# Python Code Review Report
## Files Reviewed
- app/routes/user.py (modified)
- app/services/auth.py (modified)
## Static Analysis Results
✓ ruff: No issues
✓ mypy: No errors
⚠️ black: 2 files need reformatting
✓ bandit: No security issues
## Issues Found
[CRITICAL] SQL Injection vulnerability
File: app/routes/user.py:42
Issue: User input directly interpolated into SQL query
```python
query = f"SELECT * FROM users WHERE id = {user_id}" # Bad
```
Fix: Use parameterized query
```python
query = "SELECT * FROM users WHERE id = %s" # Good
cursor.execute(query, (user_id,))
```
[HIGH] Mutable default argument
File: app/services/auth.py:18
Issue: Mutable default argument causes shared state
```python
def process_items(items=[]): # Bad
items.append("new")
return items
```
Fix: Use None as default
```python
def process_items(items=None): # Good
if items is None:
items = []
items.append("new")
return items
```
[MEDIUM] Missing type hints
File: app/services/auth.py:25
Issue: Public function without type annotations
```python
def get_user(user_id): # Bad
return db.find(user_id)
```
Fix: Add type hints
```python
def get_user(user_id: str) -> Optional[User]: # Good
return db.find(user_id)
```
[MEDIUM] Not using context manager
File: app/routes/user.py:55
Issue: File not closed on exception
```python
f = open("config.json") # Bad
data = f.read()
f.close()
```
Fix: Use context manager
```python
with open("config.json") as f: # Good
data = f.read()
```
## Summary
- CRITICAL: 1
- HIGH: 1
- MEDIUM: 2
Recommendation: ❌ Block merge until CRITICAL issue is fixed
## Formatting Required
Run: `black app/routes/user.py app/services/auth.py`
```
## Approval Criteria
| Status | Condition |
|--------|-----------|
| ✅ Approve | No CRITICAL or HIGH issues |
| ⚠️ Warning | Only MEDIUM issues (merge with caution) |
| ❌ Block | CRITICAL or HIGH issues found |
## Integration with Other Commands
- Use `/tdd` first to ensure tests pass
- Use `/code-review` for non-Python specific concerns
- Use `/python-review` before committing
- Use `/build-fix` if static analysis tools fail
## Framework-Specific Reviews
### Django Projects
The reviewer checks for:
- N+1 query issues (use `select_related` and `prefetch_related`)
- Missing migrations for model changes
- Raw SQL usage when ORM could work
- Missing `transaction.atomic()` for multi-step operations
### FastAPI Projects
The reviewer checks for:
- CORS misconfiguration
- Pydantic models for request validation
- Response models correctness
- Proper async/await usage
- Dependency injection patterns
### Flask Projects
The reviewer checks for:
- Context management (app context, request context)
- Proper error handling
- Blueprint organization
- Configuration management
## Related
- Agent: `agents/python-reviewer.md`
- Skills: `skills/python-patterns/`, `skills/python-testing/`
## Common Fixes
### Add Type Hints
```python
# Before
def calculate(x, y):
return x + y
# After
from typing import Union
def calculate(x: Union[int, float], y: Union[int, float]) -> Union[int, float]:
return x + y
```
### Use Context Managers
```python
# Before
f = open("file.txt")
data = f.read()
f.close()
# After
with open("file.txt") as f:
data = f.read()
```
### Use List Comprehensions
```python
# Before
result = []
for item in items:
if item.active:
result.append(item.name)
# After
result = [item.name for item in items if item.active]
```
### Fix Mutable Defaults
```python
# Before
def append(value, items=[]):
items.append(value)
return items
# After
def append(value, items=None):
if items is None:
items = []
items.append(value)
return items
```
### Use f-strings (Python 3.6+)
```python
# Before
name = "Alice"
greeting = "Hello, " + name + "!"
greeting2 = "Hello, {}".format(name)
# After
greeting = f"Hello, {name}!"
```
### Fix String Concatenation in Loops
```python
# Before
result = ""
for item in items:
result += str(item)
# After
result = "".join(str(item) for item in items)
```
## Python Version Compatibility
The reviewer notes when code uses features from newer Python versions:
| Feature | Minimum Python |
|---------|----------------|
| Type hints | 3.5+ |
| f-strings | 3.6+ |
| Walrus operator (`:=`) | 3.8+ |
| Position-only parameters | 3.8+ |
| Match statements | 3.10+ |
| Type unions (&#96;x &#124; None&#96;) | 3.10+ |
Ensure your project's `pyproject.toml` or `setup.py` specifies the correct minimum Python version.

80
commands/refactor-clean.md Normal file
View File

@@ -0,0 +1,80 @@
# Refactor Clean
Safely identify and remove dead code with test verification at every step.
## Step 1: Detect Dead Code
Run analysis tools based on project type:
| Tool | What It Finds | Command |
|------|--------------|---------|
| knip | Unused exports, files, dependencies | `npx knip` |
| depcheck | Unused npm dependencies | `npx depcheck` |
| ts-prune | Unused TypeScript exports | `npx ts-prune` |
| vulture | Unused Python code | `vulture src/` |
| deadcode | Unused Go code | `deadcode ./...` |
| cargo-udeps | Unused Rust dependencies | `cargo +nightly udeps` |
If no tool is available, use Grep to find exports with zero imports:
```
# Find exports, then check if they're imported anywhere
```
## Step 2: Categorize Findings
Sort findings into safety tiers:
| Tier | Examples | Action |
|------|----------|--------|
| **SAFE** | Unused utilities, test helpers, internal functions | Delete with confidence |
| **CAUTION** | Components, API routes, middleware | Verify no dynamic imports or external consumers |
| **DANGER** | Config files, entry points, type definitions | Investigate before touching |
## Step 3: Safe Deletion Loop
For each SAFE item:
1. **Run full test suite** — Establish baseline (all green)
2. **Delete the dead code** — Use Edit tool for surgical removal
3. **Re-run test suite** — Verify nothing broke
4. **If tests fail** — Immediately revert with `git checkout -- <file>` and skip this item
5. **If tests pass** — Move to next item
## Step 4: Handle CAUTION Items
Before deleting CAUTION items:
- Search for dynamic imports: `import()`, `require()`, `__import__`
- Search for string references: route names, component names in configs
- Check if exported from a public package API
- Verify no external consumers (check dependents if published)
## Step 5: Consolidate Duplicates
After removing dead code, look for:
- Near-duplicate functions (>80% similar) — merge into one
- Redundant type definitions — consolidate
- Wrapper functions that add no value — inline them
- Re-exports that serve no purpose — remove indirection
## Step 6: Summary
Report results:
```
Dead Code Cleanup
──────────────────────────────
Deleted: 12 unused functions
3 unused files
5 unused dependencies
Skipped: 2 items (tests failed)
Saved: ~450 lines removed
──────────────────────────────
All tests passing ✅
```
## Rules
- **Never delete without running tests first**
- **One deletion at a time** — Atomic changes make rollback easy
- **Skip if uncertain** — Better to keep dead code than break production
- **Don't refactor while cleaning** — Separate concerns (clean first, refactor later)

305
commands/sessions.md Normal file
View File

@@ -0,0 +1,305 @@
# Sessions Command
Manage Claude Code session history - list, load, alias, and edit sessions stored in `~/.claude/sessions/`.
## Usage
`/sessions [list|load|alias|info|help] [options]`
## Actions
### List Sessions
Display all sessions with metadata, filtering, and pagination.
```bash
/sessions # List all sessions (default)
/sessions list # Same as above
/sessions list --limit 10 # Show 10 sessions
/sessions list --date 2026-02-01 # Filter by date
/sessions list --search abc # Search by session ID
```
**Script:**
```bash
node -e "
const sm = require((process.env.CLAUDE_PLUGIN_ROOT||require('path').join(require('os').homedir(),'.claude'))+'/scripts/lib/session-manager');
const aa = require((process.env.CLAUDE_PLUGIN_ROOT||require('path').join(require('os').homedir(),'.claude'))+'/scripts/lib/session-aliases');
const result = sm.getAllSessions({ limit: 20 });
const aliases = aa.listAliases();
const aliasMap = {};
for (const a of aliases) aliasMap[a.sessionPath] = a.name;
console.log('Sessions (showing ' + result.sessions.length + ' of ' + result.total + '):');
console.log('');
console.log('ID Date Time Size Lines Alias');
console.log('────────────────────────────────────────────────────');
for (const s of result.sessions) {
const alias = aliasMap[s.filename] || '';
const size = sm.getSessionSize(s.sessionPath);
const stats = sm.getSessionStats(s.sessionPath);
const id = s.shortId === 'no-id' ? '(none)' : s.shortId.slice(0, 8);
const time = s.modifiedTime.toTimeString().slice(0, 5);
console.log(id.padEnd(8) + ' ' + s.date + ' ' + time + ' ' + size.padEnd(7) + ' ' + String(stats.lineCount).padEnd(5) + ' ' + alias);
}
"
```
### Load Session
Load and display a session's content (by ID or alias).
```bash
/sessions load <id|alias> # Load session
/sessions load 2026-02-01 # By date (for no-id sessions)
/sessions load a1b2c3d4 # By short ID
/sessions load my-alias # By alias name
```
**Script:**
```bash
node -e "
const sm = require((process.env.CLAUDE_PLUGIN_ROOT||require('path').join(require('os').homedir(),'.claude'))+'/scripts/lib/session-manager');
const aa = require((process.env.CLAUDE_PLUGIN_ROOT||require('path').join(require('os').homedir(),'.claude'))+'/scripts/lib/session-aliases');
const id = process.argv[1];
// First try to resolve as alias
const resolved = aa.resolveAlias(id);
const sessionId = resolved ? resolved.sessionPath : id;
const session = sm.getSessionById(sessionId, true);
if (!session) {
console.log('Session not found: ' + id);
process.exit(1);
}
const stats = sm.getSessionStats(session.sessionPath);
const size = sm.getSessionSize(session.sessionPath);
const aliases = aa.getAliasesForSession(session.filename);
console.log('Session: ' + session.filename);
console.log('Path: ~/.claude/sessions/' + session.filename);
console.log('');
console.log('Statistics:');
console.log(' Lines: ' + stats.lineCount);
console.log(' Total items: ' + stats.totalItems);
console.log(' Completed: ' + stats.completedItems);
console.log(' In progress: ' + stats.inProgressItems);
console.log(' Size: ' + size);
console.log('');
if (aliases.length > 0) {
console.log('Aliases: ' + aliases.map(a => a.name).join(', '));
console.log('');
}
if (session.metadata.title) {
console.log('Title: ' + session.metadata.title);
console.log('');
}
if (session.metadata.started) {
console.log('Started: ' + session.metadata.started);
}
if (session.metadata.lastUpdated) {
console.log('Last Updated: ' + session.metadata.lastUpdated);
}
" "$ARGUMENTS"
```
### Create Alias
Create a memorable alias for a session.
```bash
/sessions alias <id> <name> # Create alias
/sessions alias 2026-02-01 today-work # Create alias named "today-work"
```
**Script:**
```bash
node -e "
const sm = require((process.env.CLAUDE_PLUGIN_ROOT||require('path').join(require('os').homedir(),'.claude'))+'/scripts/lib/session-manager');
const aa = require((process.env.CLAUDE_PLUGIN_ROOT||require('path').join(require('os').homedir(),'.claude'))+'/scripts/lib/session-aliases');
const sessionId = process.argv[1];
const aliasName = process.argv[2];
if (!sessionId || !aliasName) {
console.log('Usage: /sessions alias <id> <name>');
process.exit(1);
}
// Get session filename
const session = sm.getSessionById(sessionId);
if (!session) {
console.log('Session not found: ' + sessionId);
process.exit(1);
}
const result = aa.setAlias(aliasName, session.filename);
if (result.success) {
console.log('✓ Alias created: ' + aliasName + ' → ' + session.filename);
} else {
console.log('✗ Error: ' + result.error);
process.exit(1);
}
" "$ARGUMENTS"
```
### Remove Alias
Delete an existing alias.
```bash
/sessions alias --remove <name> # Remove alias
/sessions unalias <name> # Same as above
```
**Script:**
```bash
node -e "
const aa = require((process.env.CLAUDE_PLUGIN_ROOT||require('path').join(require('os').homedir(),'.claude'))+'/scripts/lib/session-aliases');
const aliasName = process.argv[1];
if (!aliasName) {
console.log('Usage: /sessions alias --remove <name>');
process.exit(1);
}
const result = aa.deleteAlias(aliasName);
if (result.success) {
console.log('✓ Alias removed: ' + aliasName);
} else {
console.log('✗ Error: ' + result.error);
process.exit(1);
}
" "$ARGUMENTS"
```
### Session Info
Show detailed information about a session.
```bash
/sessions info <id|alias> # Show session details
```
**Script:**
```bash
node -e "
const sm = require((process.env.CLAUDE_PLUGIN_ROOT||require('path').join(require('os').homedir(),'.claude'))+'/scripts/lib/session-manager');
const aa = require((process.env.CLAUDE_PLUGIN_ROOT||require('path').join(require('os').homedir(),'.claude'))+'/scripts/lib/session-aliases');
const id = process.argv[1];
const resolved = aa.resolveAlias(id);
const sessionId = resolved ? resolved.sessionPath : id;
const session = sm.getSessionById(sessionId, true);
if (!session) {
console.log('Session not found: ' + id);
process.exit(1);
}
const stats = sm.getSessionStats(session.sessionPath);
const size = sm.getSessionSize(session.sessionPath);
const aliases = aa.getAliasesForSession(session.filename);
console.log('Session Information');
console.log('════════════════════');
console.log('ID: ' + (session.shortId === 'no-id' ? '(none)' : session.shortId));
console.log('Filename: ' + session.filename);
console.log('Date: ' + session.date);
console.log('Modified: ' + session.modifiedTime.toISOString().slice(0, 19).replace('T', ' '));
console.log('');
console.log('Content:');
console.log(' Lines: ' + stats.lineCount);
console.log(' Total items: ' + stats.totalItems);
console.log(' Completed: ' + stats.completedItems);
console.log(' In progress: ' + stats.inProgressItems);
console.log(' Size: ' + size);
if (aliases.length > 0) {
console.log('Aliases: ' + aliases.map(a => a.name).join(', '));
}
" "$ARGUMENTS"
```
### List Aliases
Show all session aliases.
```bash
/sessions aliases # List all aliases
```
**Script:**
```bash
node -e "
const aa = require((process.env.CLAUDE_PLUGIN_ROOT||require('path').join(require('os').homedir(),'.claude'))+'/scripts/lib/session-aliases');
const aliases = aa.listAliases();
console.log('Session Aliases (' + aliases.length + '):');
console.log('');
if (aliases.length === 0) {
console.log('No aliases found.');
} else {
console.log('Name Session File Title');
console.log('─────────────────────────────────────────────────────────────');
for (const a of aliases) {
const name = a.name.padEnd(12);
const file = (a.sessionPath.length > 30 ? a.sessionPath.slice(0, 27) + '...' : a.sessionPath).padEnd(30);
const title = a.title || '';
console.log(name + ' ' + file + ' ' + title);
}
}
"
```
## Arguments
$ARGUMENTS:
- `list [options]` - List sessions
- `--limit <n>` - Max sessions to show (default: 50)
- `--date <YYYY-MM-DD>` - Filter by date
- `--search <pattern>` - Search in session ID
- `load <id|alias>` - Load session content
- `alias <id> <name>` - Create alias for session
- `alias --remove <name>` - Remove alias
- `unalias <name>` - Same as `--remove`
- `info <id|alias>` - Show session statistics
- `aliases` - List all aliases
- `help` - Show this help
## Examples
```bash
# List all sessions
/sessions list
# Create an alias for today's session
/sessions alias 2026-02-01 today
# Load session by alias
/sessions load today
# Show session info
/sessions info today
# Remove alias
/sessions alias --remove today
# List all aliases
/sessions aliases
```
## Notes
- Sessions are stored as markdown files in `~/.claude/sessions/`
- Aliases are stored in `~/.claude/session-aliases.json`
- Session IDs can be shortened (first 4-8 characters usually unique enough)
- Use aliases for frequently referenced sessions

80
commands/setup-pm.md Normal file
View File

@@ -0,0 +1,80 @@
---
description: Configure your preferred package manager (npm/pnpm/yarn/bun)
disable-model-invocation: true
---
# Package Manager Setup
Configure your preferred package manager for this project or globally.
## Usage
```bash
# Detect current package manager
node scripts/setup-package-manager.js --detect
# Set global preference
node scripts/setup-package-manager.js --global pnpm
# Set project preference
node scripts/setup-package-manager.js --project bun
# List available package managers
node scripts/setup-package-manager.js --list
```
## Detection Priority
When determining which package manager to use, the following order is checked:
1. **Environment variable**: `CLAUDE_PACKAGE_MANAGER`
2. **Project config**: `.claude/package-manager.json`
3. **package.json**: `packageManager` field
4. **Lock file**: Presence of package-lock.json, yarn.lock, pnpm-lock.yaml, or bun.lockb
5. **Global config**: `~/.claude/package-manager.json`
6. **Fallback**: First available package manager (pnpm > bun > yarn > npm)
## Configuration Files
### Global Configuration
```json
// ~/.claude/package-manager.json
{
"packageManager": "pnpm"
}
```
### Project Configuration
```json
// .claude/package-manager.json
{
"packageManager": "bun"
}
```
### package.json
```json
{
"packageManager": "pnpm@8.6.0"
}
```
## Environment Variable
Set `CLAUDE_PACKAGE_MANAGER` to override all other detection methods:
```bash
# Windows (PowerShell)
$env:CLAUDE_PACKAGE_MANAGER = "pnpm"
# macOS/Linux
export CLAUDE_PACKAGE_MANAGER=pnpm
```
## Run the Detection
To see current package manager detection results, run:
```bash
node scripts/setup-package-manager.js --detect
```

72
commands/update-codemaps.md Normal file
View File

@@ -0,0 +1,72 @@
# Update Codemaps
Analyze the codebase structure and generate token-lean architecture documentation.
## Step 1: Scan Project Structure
1. Identify the project type (monorepo, single app, library, microservice)
2. Find all source directories (src/, lib/, app/, packages/)
3. Map entry points (main.ts, index.ts, app.py, main.go, etc.)
## Step 2: Generate Codemaps
Create or update codemaps in `docs/CODEMAPS/` (or `.reports/codemaps/`):
| File | Contents |
|------|----------|
| `architecture.md` | High-level system diagram, service boundaries, data flow |
| `backend.md` | API routes, middleware chain, service → repository mapping |
| `frontend.md` | Page tree, component hierarchy, state management flow |
| `data.md` | Database tables, relationships, migration history |
| `dependencies.md` | External services, third-party integrations, shared libraries |
### Codemap Format
Each codemap should be token-lean — optimized for AI context consumption:
```markdown
# Backend Architecture
## Routes
POST /api/users → UserController.create → UserService.create → UserRepo.insert
GET /api/users/:id → UserController.get → UserService.findById → UserRepo.findById
## Key Files
src/services/user.ts (business logic, 120 lines)
src/repos/user.ts (database access, 80 lines)
## Dependencies
- PostgreSQL (primary data store)
- Redis (session cache, rate limiting)
- Stripe (payment processing)
```
## Step 3: Diff Detection
1. If previous codemaps exist, calculate the diff percentage
2. If changes > 30%, show the diff and request user approval before overwriting
3. If changes <= 30%, update in place
## Step 4: Add Metadata
Add a freshness header to each codemap:
```markdown
<!-- Generated: 2026-02-11 | Files scanned: 142 | Token estimate: ~800 -->
```
## Step 5: Save Analysis Report
Write a summary to `.reports/codemap-diff.txt`:
- Files added/removed/modified since last scan
- New dependencies detected
- Architecture changes (new routes, new services, etc.)
- Staleness warnings for docs not updated in 90+ days
## Tips
- Focus on **high-level structure**, not implementation details
- Prefer **file paths and function signatures** over full code blocks
- Keep each codemap under **1000 tokens** for efficient context loading
- Use ASCII diagrams for data flow instead of verbose descriptions
- Run after major feature additions or refactoring sessions

84
commands/update-docs.md Normal file
View File

@@ -0,0 +1,84 @@
# Update Documentation
Sync documentation with the codebase, generating from source-of-truth files.
## Step 1: Identify Sources of Truth
| Source | Generates |
|--------|-----------|
| `package.json` scripts | Available commands reference |
| `.env.example` | Environment variable documentation |
| `openapi.yaml` / route files | API endpoint reference |
| Source code exports | Public API documentation |
| `Dockerfile` / `docker-compose.yml` | Infrastructure setup docs |
## Step 2: Generate Script Reference
1. Read `package.json` (or `Makefile`, `Cargo.toml`, `pyproject.toml`)
2. Extract all scripts/commands with their descriptions
3. Generate a reference table:
```markdown
| Command | Description |
|---------|-------------|
| `npm run dev` | Start development server with hot reload |
| `npm run build` | Production build with type checking |
| `npm test` | Run test suite with coverage |
```
## Step 3: Generate Environment Documentation
1. Read `.env.example` (or `.env.template`, `.env.sample`)
2. Extract all variables with their purposes
3. Categorize as required vs optional
4. Document expected format and valid values
```markdown
| Variable | Required | Description | Example |
|----------|----------|-------------|---------|
| `DATABASE_URL` | Yes | PostgreSQL connection string | `postgres://user:pass@host:5432/db` |
| `LOG_LEVEL` | No | Logging verbosity (default: info) | `debug`, `info`, `warn`, `error` |
```
## Step 4: Update Contributing Guide
Generate or update `docs/CONTRIBUTING.md` with:
- Development environment setup (prerequisites, install steps)
- Available scripts and their purposes
- Testing procedures (how to run, how to write new tests)
- Code style enforcement (linter, formatter, pre-commit hooks)
- PR submission checklist
## Step 5: Update Runbook
Generate or update `docs/RUNBOOK.md` with:
- Deployment procedures (step-by-step)
- Health check endpoints and monitoring
- Common issues and their fixes
- Rollback procedures
- Alerting and escalation paths
## Step 6: Staleness Check
1. Find documentation files not modified in 90+ days
2. Cross-reference with recent source code changes
3. Flag potentially outdated docs for manual review
## Step 7: Show Summary
```
Documentation Update
──────────────────────────────
Updated: docs/CONTRIBUTING.md (scripts table)
Updated: docs/ENV.md (3 new variables)
Flagged: docs/DEPLOY.md (142 days stale)
Skipped: docs/API.md (no changes detected)
──────────────────────────────
```
## Rules
- **Single source of truth**: Always generate from code, never manually edit generated sections
- **Preserve manual sections**: Only update generated sections; leave hand-written prose intact
- **Mark generated content**: Use `<!-- AUTO-GENERATED -->` markers around generated sections
- **Don't create docs unprompted**: Only create new doc files if the command explicitly requests it