@cregis-dev/cckit 0.5.0 → 0.6.2

package/registry.json

@@ -1,92 +1,116 @@
-{
-  "version": "2.0.0",
-  "plugins": {
-    "everything-claude-code": {
-      "name": "Everything Claude Code",
-      "marketplace": "everything-claude-code",
-      "marketplaceSource": {
-        "source": "github",
-        "repo": "affaan-m/everything-claude-code"
-      },
-      "default": true,
-      "description": "Rules, agents, commands, skills, and hooks for Claude Code"
-    },
-    "superpowers": {
-      "name": "Superpowers",
-      "marketplace": "claude-plugins-official",
-      "default": true,
-      "description": "Structured workflows with brainstorming, debugging, TDD, and code review skills"
-    },
-    "claude-code-setup": {
-      "name": "Claude Code Setup",
-      "marketplace": "claude-plugins-official",
-      "default": true,
-      "description": "Analyze codebases and recommend Claude Code automations, audit and improve CLAUDE.md files"
-    },
-    "claude-md-management": {
-      "name": "Claude MD Management",
-      "marketplace": "claude-plugins-official",
-      "default": true,
-      "description": "Audit, improve, and update CLAUDE.md documentation files"
-    },
-    "code-simplifier": {
-      "name": "Code Simplifier",
-      "marketplace": "claude-plugins-official",
-      "default": true,
-      "description": "Simplify and refine code for clarity, consistency, and maintainability"
-    },
-    "commit-commands": {
-      "name": "Commit Commands",
-      "marketplace": "claude-plugins-official",
-      "default": true,
-      "description": "Git commit workflows: commit, push, PR creation, and branch cleanup"
-    },
-    "firecrawl": {
-      "name": "Firecrawl",
-      "marketplace": "claude-plugins-official",
-      "default": true,
-      "description": "Web scraping, search, and skill generation using Firecrawl"
-    }
-  },
-  "rules": {
-    "ecc": {
-      "repo": "https://github.com/affaan-m/everything-claude-code",
-      "rulesPath": "rules",
-      "target": ".claude/rules",
-      "cacheKey": "ecc-rules"
-    }
-  },
-  "skills": [
-    {
-      "id": "pinchtab",
-      "repo": "https://github.com/pinchtab/pinchtab",
-      "skill": "pinchtab"
-    }
-  ],
-  "bmad": {
-    "command": "npx",
-    "args": ["bmad-method", "install", "--directory", ".", "--modules", "bmm,tea", "--communication-language", "Chinese", "--document-output-language", "Chinese", "--tools", "claude-code", "--yes", "--action", "quick-update"],
-    "outputDirs": ["_bmad/core", "_bmad/bmm", "_bmad/tea", ".claude/commands"]
-  },
-  "mcp": {
-    "template": "templates/mcp/claude-code/.mcp.json",
-    "target": ".mcp.json"
-  },
-  "userSettings": {
-    "apiUrl": "https://gateway.cregis.ai",
-    "models": {
-      "minimax": "MiniMax-M2.5",
-      "kimi": "Kimi-K2.5",
-      "gemini": "gemini-3.1-pro-preview",
-      "gpt": "gpt-5.3-codex"
-    },
-    "defaultModel": "minimax",
-    "modelEnvKeys": [
-      "ANTHROPIC_MODEL",
-      "ANTHROPIC_SMALL_FAST_MODEL",
-      "ANTHROPIC_DEFAULT_SONNET_MODEL",
-      "ANTHROPIC_DEFAULT_OPUS_MODEL",
-      "ANTHROPIC_DEFAULT_HAIKU_MODEL"
-    ]
-  }
-}
+{
+  "version": "2.0.0",
+  "plugins": {
+    "everything-claude-code": {
+      "name": "Everything Claude Code",
+      "marketplace": "everything-claude-code",
+      "marketplaceSource": {
+        "source": "github",
+        "repo": "affaan-m/everything-claude-code"
+      },
+      "default": true,
+      "description": "Rules, agents, commands, skills, and hooks for Claude Code"
+    },
+    "superpowers": {
+      "name": "Superpowers",
+      "marketplace": "claude-plugins-official",
+      "default": true,
+      "description": "Structured workflows with brainstorming, debugging, TDD, and code review skills"
+    },
+    "claude-code-setup": {
+      "name": "Claude Code Setup",
+      "marketplace": "claude-plugins-official",
+      "default": true,
+      "description": "Analyze codebases and recommend Claude Code automations, audit and improve CLAUDE.md files"
+    },
+    "claude-md-management": {
+      "name": "Claude MD Management",
+      "marketplace": "claude-plugins-official",
+      "default": true,
+      "description": "Audit, improve, and update CLAUDE.md documentation files"
+    },
+    "code-simplifier": {
+      "name": "Code Simplifier",
+      "marketplace": "claude-plugins-official",
+      "default": true,
+      "description": "Simplify and refine code for clarity, consistency, and maintainability"
+    },
+    "commit-commands": {
+      "name": "Commit Commands",
+      "marketplace": "claude-plugins-official",
+      "default": true,
+      "description": "Git commit workflows: commit, push, PR creation, and branch cleanup"
+    },
+    "firecrawl": {
+      "name": "Firecrawl",
+      "marketplace": "claude-plugins-official",
+      "default": true,
+      "description": "Web scraping, search, and skill generation using Firecrawl"
+    }
+  },
+  "rules": {
+    "template": "templates/rules",
+    "target": ".claude/rules"
+  },
+  "skills": [
+    {
+      "id": "pinchtab",
+      "repo": "https://github.com/pinchtab/pinchtab",
+      "skill": "pinchtab",
+      "installCommand": "npx skills add https://github.com/pinchtab/pinchtab --skill pinchtab -y -a claude-code"
+    },
+    {
+      "id": "find-skills",
+      "repo": "https://github.com/vercel-labs/skills",
+      "skill": "find-skills",
+      "installCommand": "npx skills add https://github.com/vercel-labs/skills --skill find-skills -y -a claude-code"
+    },
+    {
+      "id": "skill-vetter",
+      "repo": "https://github.com/useai-pro/openclaw-skills-security",
+      "skill": "skill-vetter",
+      "installCommand": "npx skills add https://github.com/useai-pro/openclaw-skills-security@skill-vetter -y -a claude-code"
+    }
+  ],
+  "bmad": {
+    "command": "npx",
+    "args": [
+      "bmad-method",
+      "install",
+      "--directory",
+      ".",
+      "--modules",
+      "bmm,tea",
+      "--communication-language",
+      "Chinese",
+      "--document-output-language",
+      "Chinese",
+      "--tools",
+      "claude-code",
+      "--yes",
+      "--output-folder",
+      "_bmad-output"
+    ]
+  },
+  "mcp": {
+    "template": "templates/mcp/claude-code/.mcp.json",
+    "target": ".mcp.json"
+  },
+  "userSettings": {
+    "apiUrl": "https://gateway.cregis.ai",
+    "models": {
+      "minimax": "MiniMax-M2.5",
+      "kimi": "Kimi-K2.5",
+      "gemini": "gemini-3.1-pro-preview",
+      "gpt": "gpt-5.3-codex"
+    },
+    "defaultModel": "minimax",
+    "modelEnvKeys": [
+      "ANTHROPIC_MODEL",
+      "ANTHROPIC_SMALL_FAST_MODEL",
+      "ANTHROPIC_DEFAULT_SONNET_MODEL",
+      "ANTHROPIC_DEFAULT_OPUS_MODEL",
+      "ANTHROPIC_DEFAULT_HAIKU_MODEL"
+    ]
+  }
+}

package/src/cli.js

@@ -11,8 +11,8 @@ export function run(argv) {
     .version(VERSION)
 
   program
-    .command('init')
-    .description('Initialize project with enterprise Claude Code configuration')
+    .command('install')
+    .description('Install enterprise Claude Code configuration')
     .option('-y, --yes', 'Accept all defaults', false)
     .option('-d, --dir <path>', 'Target directory', process.cwd())
     .option('--user-name <name>', 'Your name for agents')

package/src/commands/init.js

@@ -105,7 +105,7 @@ export async function runInit(opts = {}, _deps = {}) {
       fn: _deps.installRules || installRules,
       opts: {
         targetDir,
-        rulesConfig: registry.rules.ecc,
+        rulesConfig: registry.rules,
         skip: config.excludeGroups.includes('ecc'),
       },
     },

package/src/commands/update.js

@@ -112,7 +112,7 @@ export async function runUpdate(opts = {}, _deps = {}) {
       fn: _deps.installRules || installRules,
       opts: {
         targetDir,
-        rulesConfig: registry.rules.ecc,
+        rulesConfig: registry.rules,
         skip: false,
         forceRefresh: true,
       },

package/src/steps/configure-user.js

@@ -47,8 +47,14 @@ export async function configureUser(opts, logger, _deps = {}) {
 
   const existingEnv = existing.env || {}
 
-  // 1. API URL — always set (default or override)
-  const apiUrl = opts.apiUrl
+  // 1. API URL — prompt for confirmation if not provided via CLI
+  let apiUrl = opts.apiUrl
+  if (!opts.yes && !opts.apiUrl) {
+    const input = await askFn('  Enter API URL (default: ' + opts.apiUrl + '): ')
+    if (input && input.trim()) {
+      apiUrl = input.trim()
+    }
+  }
 
   // 2. API Key — resolve from CLI flag, readline, or existing
   let apiKey = existingEnv.ANTHROPIC_AUTH_TOKEN || ''
@@ -67,19 +73,28 @@ export async function configureUser(opts, logger, _deps = {}) {
       if (input) {
         apiKey = input
       } else if (!hasExistingKey) {
-        logger.warn('No API Key provided. You can set it later with `cckit init --api-key <key>`')
+        logger.warn('No API Key provided. You can set it later with `cckit install --api-key <key>`')
       }
     }
     // --yes mode without --api-key: skip prompt, keep existing
   }
 
-  // 3. Model env vars
+  // 3. Model — prompt for confirmation
+  let modelId = opts.modelId
+  if (!opts.yes && !opts.model) {
+    const input = await askFn('  Enter model (default: ' + opts.modelId + '): ')
+    if (input && input.trim()) {
+      modelId = input.trim()
+    }
+  }
+
+  // 4. Model env vars
   const modelEnvEntries = {}
   for (const key of opts.modelEnvKeys) {
-    modelEnvEntries[key] = opts.modelId
+    modelEnvEntries[key] = modelId
   }
 
-  // 4. Merge and write
+  // 5. Merge and write
   const merged = {
     ...existing,
     env: {
@@ -97,7 +112,7 @@ export async function configureUser(opts, logger, _deps = {}) {
 
   logger.info(`  API URL:   ${apiUrl}`)
   logger.info(`  API Key:   ${maskedKey}`)
-  logger.info(`  Model:     ${opts.modelId}`)
+  logger.info(`  Model:     ${modelId}`)
   logger.info(`  Settings:  ${settingsPath}`)
 
   return {
@@ -108,7 +123,7 @@ export async function configureUser(opts, logger, _deps = {}) {
     details: {
       apiUrl,
       hasApiKey: Boolean(apiKey),
-      modelId: opts.modelId,
+      modelId,
       settingsPath,
     },
   }

package/src/steps/install-rules.js

@@ -1,60 +1,21 @@
 /**
- * Step: Install ECC rules via git clone + copy.
+ * Step: Install ECC rules via template copy.
  *
- * Clones the ECC repository to a user-level cache directory,
- * then copies the `rules/` subtree to `.claude/rules/`.
- * Cache is reused within 24 hours.
+ * Copies the bundled rules template to `.claude/rules/`.
  */
 
-import { execFile } from 'node:child_process'
-import { promisify } from 'node:util'
-import os from 'node:os'
 import path from 'node:path'
 import fse from 'fs-extra'
 import { listFiles } from '../utils/fs.js'
+import { fileURLToPath } from 'node:url'
 
-const execFileAsync = promisify(execFile)
-
-const CACHE_MAX_AGE_MS = 24 * 60 * 60 * 1000 // 24 hours
-
-/**
- * Clone a git repo to cache, reusing if fresh.
- *
- * @param {string} cacheKey - Cache directory name
- * @param {string} repo - Git repository URL
- * @param {boolean} forceRefresh - Force re-clone even if cache exists
- * @param {object} [_deps] - Injectable dependencies
- * @returns {Promise<string>} Absolute path to cached clone
- */
-async function getCachedClone(cacheKey, repo, forceRefresh = false, _deps = {}) {
-  const { execFileFn = execFileAsync } = _deps
-  const cacheBase = path.join(os.homedir(), '.cckit', 'cache')
-  const cacheDir = path.join(cacheBase, cacheKey)
-
-  if (!forceRefresh && await fse.pathExists(cacheDir)) {
-    const stat = await fse.stat(cacheDir)
-    const ageMs = Date.now() - stat.mtimeMs
-    if (ageMs < CACHE_MAX_AGE_MS) {
-      return cacheDir
-    }
-  }
-
-  // Remove stale cache if exists
-  if (await fse.pathExists(cacheDir)) {
-    await fse.remove(cacheDir)
-  }
-
-  await fse.ensureDir(cacheBase)
-  await execFileFn('git', ['clone', '--depth', '1', repo, cacheDir])
-  return cacheDir
-}
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
 
 /**
  * @param {object} opts
  * @param {string} opts.targetDir - Project root
- * @param {object} opts.rulesConfig - { repo, rulesPath, target, cacheKey }
+ * @param {object} opts.rulesConfig - { template, target }
  * @param {boolean} opts.skip - Skip this step
- * @param {boolean} [opts.forceRefresh] - Force re-clone
  * @param {object} logger
  * @param {object} [_deps] - Injectable dependencies
  * @returns {Promise<import('../core/orchestrator.js').StepResult>}
@@ -64,28 +25,26 @@ export async function installRules(opts, logger, _deps = {}) {
     return { stepId: 'install-rules', name: 'Install ECC Rules', success: true, skipped: true, details: {} }
   }
 
-  const { repo, rulesPath, target, cacheKey } = opts.rulesConfig
+  const { template, target } = opts.rulesConfig
 
   try {
-    logger.info('  Cloning ECC rules repository...')
-    const cloneDir = await getCachedClone(cacheKey, repo, opts.forceRefresh, _deps)
-
-    const srcDir = path.join(cloneDir, rulesPath)
+    // Resolve template path - use absolute path if provided, otherwise relative to cckit package
+    const templatePath = path.resolve(__dirname, '../../', template)
     const destDir = path.join(opts.targetDir, target)
 
-    if (!await fse.pathExists(srcDir)) {
+    if (!await fse.pathExists(templatePath)) {
       return {
         stepId: 'install-rules',
         name: 'Install ECC Rules',
         success: false,
         skipped: false,
         details: {},
-        error: `Rules path "${rulesPath}" not found in cloned repository`,
+        error: `Rules template not found: ${templatePath}`,
       }
     }
 
     await fse.ensureDir(destDir)
-    await fse.copy(srcDir, destDir, { overwrite: true })
+    await fse.copy(templatePath, destDir, { overwrite: true })
 
     const files = await listFiles(destDir)
     logger.debug(`Copied ${files.length} rule files to ${target}`)

package/templates/rules/README.md

@@ -0,0 +1,103 @@
+# Rules
+## Structure
+
+Rules are organized into a **common** layer plus **language-specific** directories:
+
+```
+rules/
+├── common/          # Language-agnostic principles (always install)
+│   ├── coding-style.md
+│   ├── git-workflow.md
+│   ├── testing.md
+│   ├── performance.md
+│   ├── patterns.md
+│   ├── hooks.md
+│   ├── agents.md
+│   └── security.md
+├── typescript/      # TypeScript/JavaScript specific
+├── python/          # Python specific
+├── golang/          # Go specific
+└── swift/           # Swift specific
+```
+
+- **common/** contains universal principles — no language-specific code examples.
+- **Language directories** extend the common rules with framework-specific patterns, tools, and code examples. Each file references its common counterpart.
+
+## Installation
+
+### Option 1: Install Script (Recommended)
+
+```bash
+# Install common + one or more language-specific rule sets
+./install.sh typescript
+./install.sh python
+./install.sh golang
+./install.sh swift
+
+# Install multiple languages at once
+./install.sh typescript python
+```
+
+### Option 2: Manual Installation
+
+> **Important:** Copy entire directories — do NOT flatten with `/*`.
+> Common and language-specific directories contain files with the same names.
+> Flattening them into one directory causes language-specific files to overwrite
+> common rules, and breaks the relative `../common/` references used by
+> language-specific files.
+
+```bash
+# Install common rules (required for all projects)
+cp -r rules/common ~/.claude/rules/common
+
+# Install language-specific rules based on your project's tech stack
+cp -r rules/typescript ~/.claude/rules/typescript
+cp -r rules/python ~/.claude/rules/python
+cp -r rules/golang ~/.claude/rules/golang
+cp -r rules/swift ~/.claude/rules/swift
+
+# Attention ! ! ! Configure according to your actual project requirements; the configuration here is for reference only.
+```
+
+## Rules vs Skills
+
+- **Rules** define standards, conventions, and checklists that apply broadly (e.g., "80% test coverage", "no hardcoded secrets").
+- **Skills** (`skills/` directory) provide deep, actionable reference material for specific tasks (e.g., `python-patterns`, `golang-testing`).
+
+Language-specific rule files reference relevant skills where appropriate. Rules tell you *what* to do; skills tell you *how* to do it.
+
+## Adding a New Language
+
+To add support for a new language (e.g., `rust/`):
+
+1. Create a `rules/rust/` directory
+2. Add files that extend the common rules:
+   - `coding-style.md` — formatting tools, idioms, error handling patterns
+   - `testing.md` — test framework, coverage tools, test organization
+   - `patterns.md` — language-specific design patterns
+   - `hooks.md` — PostToolUse hooks for formatters, linters, type checkers
+   - `security.md` — secret management, security scanning tools
+3. Each file should start with:
+   ```
+   > This file extends [common/xxx.md](../common/xxx.md) with <Language> specific content.
+   ```
+4. Reference existing skills if available, or create new ones under `skills/`.
+
+## Rule Priority
+
+When language-specific rules and common rules conflict, **language-specific rules take precedence** (specific overrides general). This follows the standard layered configuration pattern (similar to CSS specificity or `.gitignore` precedence).
+
+- `rules/common/` defines universal defaults applicable to all projects.
+- `rules/golang/`, `rules/python/`, `rules/typescript/`, etc. override those defaults where language idioms differ.
+
+### Example
+
+`common/coding-style.md` recommends immutability as a default principle. A language-specific `golang/coding-style.md` can override this:
+
+> Idiomatic Go uses pointer receivers for struct mutation — see [common/coding-style.md](../common/coding-style.md) for the general principle, but Go-idiomatic mutation is preferred here.
+
+### Common rules with override notes
+
+Rules in `rules/common/` that may be overridden by language-specific files are marked with:
+
+> **Language note**: This rule may be overridden by language-specific rules for languages where this pattern is not idiomatic.

package/templates/rules/common/agents.md

@@ -0,0 +1,49 @@
+# Agent Orchestration
+
+## Available Agents
+
+Located in `~/.claude/agents/`:
+
+| Agent | Purpose | When to Use |
+|-------|---------|-------------|
+| planner | Implementation planning | Complex features, refactoring |
+| architect | System design | Architectural decisions |
+| tdd-guide | Test-driven development | New features, bug fixes |
+| code-reviewer | Code review | After writing code |
+| security-reviewer | Security analysis | Before commits |
+| build-error-resolver | Fix build errors | When build fails |
+| e2e-runner | E2E testing | Critical user flows |
+| refactor-cleaner | Dead code cleanup | Code maintenance |
+| doc-updater | Documentation | Updating docs |
+
+## Immediate Agent Usage
+
+No user prompt needed:
+1. Complex feature requests - Use **planner** agent
+2. Code just written/modified - Use **code-reviewer** agent
+3. Bug fix or new feature - Use **tdd-guide** agent
+4. Architectural decision - Use **architect** agent
+
+## Parallel Task Execution
+
+ALWAYS use parallel Task execution for independent operations:
+
+```markdown
+# GOOD: Parallel execution
+Launch 3 agents in parallel:
+1. Agent 1: Security analysis of auth module
+2. Agent 2: Performance review of cache system
+3. Agent 3: Type checking of utilities
+
+# BAD: Sequential when unnecessary
+First agent 1, then agent 2, then agent 3
+```
+
+## Multi-Perspective Analysis
+
+For complex problems, use split role sub-agents:
+- Factual reviewer
+- Senior engineer
+- Security expert
+- Consistency reviewer
+- Redundancy checker

package/templates/rules/common/coding-style.md

@@ -0,0 +1,48 @@
+# Coding Style
+
+## Immutability (CRITICAL)
+
+ALWAYS create new objects, NEVER mutate existing ones:
+
+```
+// Pseudocode
+WRONG:  modify(original, field, value) → changes original in-place
+CORRECT: update(original, field, value) → returns new copy with change
+```
+
+Rationale: Immutable data prevents hidden side effects, makes debugging easier, and enables safe concurrency.
+
+## File Organization
+
+MANY SMALL FILES > FEW LARGE FILES:
+- High cohesion, low coupling
+- 200-400 lines typical, 800 max
+- Extract utilities from large modules
+- Organize by feature/domain, not by type
+
+## Error Handling
+
+ALWAYS handle errors comprehensively:
+- Handle errors explicitly at every level
+- Provide user-friendly error messages in UI-facing code
+- Log detailed error context on the server side
+- Never silently swallow errors
+
+## Input Validation
+
+ALWAYS validate at system boundaries:
+- Validate all user input before processing
+- Use schema-based validation where available
+- Fail fast with clear error messages
+- Never trust external data (API responses, user input, file content)
+
+## Code Quality Checklist
+
+Before marking work complete:
+- [ ] Code is readable and well-named
+- [ ] Functions are small (<50 lines)
+- [ ] Files are focused (<800 lines)
+- [ ] No deep nesting (>4 levels)
+- [ ] Proper error handling
+- [ ] No hardcoded values (use constants or config)
+- [ ] No mutation (immutable patterns used)

package/templates/rules/common/development-workflow.md

@@ -0,0 +1,37 @@
+# Development Workflow
+
+> This file extends [common/git-workflow.md](./git-workflow.md) with the full feature development process that happens before git operations.
+
+The Feature Implementation Workflow describes the development pipeline: research, planning, TDD, code review, and then committing to git.
+
+## Feature Implementation Workflow
+
+0. **Research & Reuse** _(mandatory before any new implementation)_
+   - **GitHub code search first:** Run `gh search repos` and `gh search code` to find existing implementations, templates, and patterns before writing anything new.
+   - **Exa MCP for research:** Use `exa-web-search` MCP during the planning phase for broader research, data ingestion, and discovering prior art.
+   - **Check package registries:** Search npm, PyPI, crates.io, and other registries before writing utility code. Prefer battle-tested libraries over hand-rolled solutions.
+   - **Search for adaptable implementations:** Look for open-source projects that solve 80%+ of the problem and can be forked, ported, or wrapped.
+   - Prefer adopting or porting a proven approach over writing net-new code when it meets the requirement.
+
+1. **Plan First**
+   - Use **planner** agent to create implementation plan
+   - Generate planning docs before coding: PRD, architecture, system_design, tech_doc, task_list
+   - Identify dependencies and risks
+   - Break down into phases
+
+2. **TDD Approach**
+   - Use **tdd-guide** agent
+   - Write tests first (RED)
+   - Implement to pass tests (GREEN)
+   - Refactor (IMPROVE)
+   - Verify 80%+ coverage
+
+3. **Code Review**
+   - Use **code-reviewer** agent immediately after writing code
+   - Address CRITICAL and HIGH issues
+   - Fix MEDIUM issues when possible
+
+4. **Commit & Push**
+   - Detailed commit messages
+   - Follow conventional commits format
+   - See [git-workflow.md](./git-workflow.md) for commit message format and PR process