create-harness-vibe-coding 0.1.0

package/bin/create-harness-vibe-coding.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../src/index.js');

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "create-harness-vibe-coding",
+  "version": "0.1.0",
+  "description": "Scaffold a vibe-coding agentic harness — CLAUDE.md, docs/, .claude skeleton ready for ECC agents/skills/rules",
+  "type": "module",
+  "bin": {
+    "create-harness-vibe-coding": "./bin/create-harness-vibe-coding.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "templates/"
+  ],
+  "scripts": {
+    "start": "node src/index.js"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.7.0",
+    "picocolors": "^1.1.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/LiWeny16/q-profit.git",
+    "directory": "create-harness-vibe-coding"
+  },
+  "keywords": [
+    "claude-code",
+    "harness",
+    "scaffold",
+    "vibe-coding",
+    "agentic",
+    "ecc",
+    "superpowers"
+  ],
+  "license": "MIT"
+}

package/src/generator.js

@@ -0,0 +1,107 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import pc from 'picocolors';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = path.resolve(__dirname, '..', 'templates', 'common');
+
+/**
+ * Copy a directory recursively, replacing {{vars}} in file contents.
+ * Skips dirs named '.gitkeep-placeholder'.
+ */
+function copyDir(src, dest, vars) {
+  fs.mkdirSync(dest, { recursive: true });
+
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath, vars);
+    } else {
+      let content = fs.readFileSync(srcPath, 'utf-8');
+
+      // Replace template variables
+      for (const [key, value] of Object.entries(vars)) {
+        content = content.replaceAll(`{{${key}}}`, value);
+      }
+
+      fs.writeFileSync(destPath, content, 'utf-8');
+    }
+  }
+}
+
+/**
+ * Walk a directory and return relative paths of all files.
+ */
+function walkFiles(dir, base = dir) {
+  const results = [];
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...walkFiles(full, base));
+    } else {
+      results.push(path.relative(base, full));
+    }
+  }
+
+  return results;
+}
+
+export function generate({ projectName, targetDir }) {
+  const created = [];
+  const errors = [];
+
+  // Resolve targetDir relative to cwd
+  const resolvedDir = path.resolve(process.cwd(), targetDir);
+
+  // Check if target exists and is non-empty
+  if (fs.existsSync(resolvedDir)) {
+    const existing = fs.readdirSync(resolvedDir).filter(f => f !== '.git');
+    if (existing.length > 0) {
+      console.log(pc.yellow(`⚠ 目录 "${targetDir}" 已存在且非空，文件可能被覆盖`));
+    }
+  }
+
+  const vars = { projectName };
+
+  try {
+    // 1. Copy all template files
+    console.log(pc.cyan('📋 复制模板文件...'));
+    copyDir(TEMPLATES_DIR, resolvedDir, vars);
+
+    // List all created files from templates
+    created.push(...walkFiles(TEMPLATES_DIR).map(f => f.replace(/\\/g, '/')));
+
+    // 2. Create empty directories
+    console.log(pc.cyan('📁 创建占位目录...'));
+    const emptyDirs = [
+      '.claude/agents',
+      '.claude/skills',
+      '.claude/hooks',
+      'tests',
+    ];
+
+    for (const dir of emptyDirs) {
+      const dirPath = path.join(resolvedDir, dir);
+      fs.mkdirSync(dirPath, { recursive: true });
+      created.push(`${dir}/ (empty)`);
+    }
+
+    // 3. Create .gitkeep in tests/
+    const gitkeepPath = path.join(resolvedDir, 'tests', '.gitkeep');
+    fs.writeFileSync(gitkeepPath, '', 'utf-8');
+    created.push('tests/.gitkeep');
+
+    return { success: true, created, errors };
+
+  } catch (err) {
+    errors.push(err.message);
+    return { success: false, created, errors };
+  }
+}

package/src/index.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import { askProjectName, askTargetDir } from './prompts.js';
+import { generate } from './generator.js';
+
+// Parse CLI args for non-interactive mode
+const args = process.argv.slice(2);
+const argName = args[0];
+const argDir = args[1];
+
+console.log('');
+console.log(pc.magenta('╔══════════════════════════════════════════╗'));
+console.log(pc.magenta('║   🎯 create-harness-vibe-coding          ║'));
+console.log(pc.magenta('║   Agentic Harness — Vibe Coding Ready    ║'));
+console.log(pc.magenta('╚══════════════════════════════════════════╝'));
+console.log('');
+
+let projectName, targetDir;
+
+// Non-interactive mode: use CLI args or defaults
+if (argName) {
+  projectName = argName;
+  targetDir = argDir || `./${projectName}`;
+
+  console.log(pc.dim('────────────────────────────────────────────'));
+  console.log(`  项目名称  ${pc.green(projectName)}`);
+  console.log(`  目标目录  ${pc.green(targetDir)}`);
+  console.log(`  将创建    ${pc.cyan('CLAUDE.md, docs/, .claude/, SETUP.md, tests/')}`);
+  console.log(pc.dim('────────────────────────────────────────────'));
+  console.log('');
+
+  const result = generate({ projectName, targetDir });
+  printResult(result, targetDir);
+} else {
+  // Interactive mode
+  try {
+    projectName = await askProjectName();
+  } catch {
+    // Fallback for non-TTY
+    projectName = 'my-vibe-project';
+    console.log(pc.dim(`  项目名称: ${projectName} (默认)`));
+  }
+
+  try {
+    targetDir = await askTargetDir(projectName);
+  } catch {
+    targetDir = `./${projectName}`;
+    console.log(pc.dim(`  目标目录: ${targetDir} (默认)`));
+  }
+
+  console.log('');
+  console.log(pc.dim('────────────────────────────────────────────'));
+  console.log(`  项目名称  ${pc.green(projectName)}`);
+  console.log(`  目标目录  ${pc.green(targetDir)}`);
+  console.log(`  将创建    ${pc.cyan('CLAUDE.md, docs/, .claude/, SETUP.md, tests/')}`);
+  console.log(pc.dim('────────────────────────────────────────────'));
+  console.log('');
+
+  let proceed = true;
+  try {
+    proceed = await p.confirm({
+      message: '确认生成?',
+      initialValue: true,
+    });
+    if (p.isCancel(proceed)) proceed = false;
+  } catch {
+    proceed = true;
+  }
+
+  if (!proceed) {
+    p.cancel('已取消');
+    process.exit(0);
+  }
+
+  console.log('');
+  const result = generate({ projectName, targetDir });
+  printResult(result, targetDir);
+}
+
+function printResult(result, targetDir) {
+  if (result.success) {
+    console.log(pc.green(`\n✅ 项目已创建! 共 ${result.created.length} 个文件\n`));
+
+    console.log(pc.bold('下一步:'));
+    console.log(`  ${pc.cyan(`cd ${targetDir}`)}`);
+    console.log(`  ${pc.cyan('claude')}                          # 启动 Claude Code`);
+    console.log(`  告诉 Claude: "${pc.yellow('阅读 SETUP.md 并帮我初始化项目')}"`);
+    console.log('');
+    console.log(pc.dim('  SETUP.md 是临时文件，初始化完成后可删除'));
+    console.log('');
+
+    if (result.errors.length > 0) {
+      console.log(pc.red(`\n⚠ ${result.errors.length} 个警告:`));
+      for (const err of result.errors) {
+        console.log(pc.red(`  - ${err}`));
+      }
+    }
+  } else {
+    console.log(pc.red('\n❌ 生成失败:'));
+    for (const err of result.errors) {
+      console.log(pc.red(`  - ${err}`));
+    }
+    process.exit(1);
+  }
+}

package/src/prompts.js

@@ -0,0 +1,41 @@
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+
+export async function askProjectName() {
+  const name = await p.text({
+    message: '项目名称?',
+    placeholder: 'my-vibe-project',
+    defaultValue: 'my-vibe-project',
+    validate(value) {
+      if (!value.trim()) return '项目名不能为空';
+      if (!/^[a-zA-Z0-9_-]+$/.test(value)) return '只允许字母、数字、连字符和下划线';
+      return;
+    },
+  });
+
+  if (p.isCancel(name)) {
+    p.cancel('已取消');
+    process.exit(0);
+  }
+
+  return name.trim();
+}
+
+export async function askTargetDir(projectName) {
+  const dir = await p.text({
+    message: '目标目录?',
+    placeholder: `./${projectName}`,
+    defaultValue: `./${projectName}`,
+    validate(value) {
+      if (!value.trim()) return '目录不能为空';
+      return;
+    },
+  });
+
+  if (p.isCancel(dir)) {
+    p.cancel('已取消');
+    process.exit(0);
+  }
+
+  return dir.trim();
+}

package/templates/common/.claude/rules/ecc/common.md

@@ -0,0 +1,32 @@
+---
+description: "Universal coding principles — always applied"
+alwaysApply: true
+---
+
+# Universal Coding Rules
+
+## Architecture Boundaries (CLAUDE.md enforced)
+- `domain/` depends on stdlib only — no infrastructure imports ever
+- `application/` depends on `domain/` only
+- `infrastructure/` implements ports defined in `domain/`
+- `harness/` coordinates workflows, contains no domain business rules
+
+## Code Style
+- Prefer small, deterministic, pure functions
+- Functions > 30 lines need a comment explaining why they can't be split
+- No hidden global state in strategy or service objects
+- Explicit over implicit: type hints on all function signatures
+
+## Git Workflow
+- Commit format: `type(scope): message` — types: feat/fix/test/docs/refactor/chore
+- Every feature PR must include: implementation + tests + doc update
+- Keep commits atomic; one logical change per commit
+
+## Testing
+- Write tests before or alongside implementation, not after
+- Test behavior, not implementation details
+- Tests must be deterministic and not depend on wall-clock time
+
+## Security
+- No API keys or secrets in source code — use environment variables
+- Validate all external data at system boundaries

package/templates/common/.claude/settings.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "permissions": {
+    "allow": [
+      "Bash(git *)",
+      "Bash(npm *)",
+      "Bash(npx *)",
+      "Bash(python *)",
+      "Bash(pytest *)",
+      "Bash(pip *)",
+      "Bash(go *)",
+      "Bash(cargo *)",
+      "Bash(node *)",
+      "Read",
+      "Glob",
+      "Grep",
+      "WebFetch",
+      "WebSearch"
+    ],
+    "deny": [
+      "Bash(rm -rf *)",
+      "Bash(sudo *)",
+      "Bash(curl *)",
+      "Bash(wget *)",
+      "Bash(> *)",
+      "Read(.env*)",
+      "Read(**/secrets/**)",
+      "Read(**/*.key)",
+      "Read(**/*.pem)"
+    ]
+  },
+  "hooks": {
+  }
+}

package/templates/common/AGENTS.md

@@ -0,0 +1,5 @@
+# AGENTS.md
+
+Entry point for coding agents.
+
+Read `CLAUDE.md` first, then follow docs in `docs/`.

package/templates/common/CLAUDE.md

@@ -0,0 +1,119 @@
+# CLAUDE.md
+
+@docs/README.md
+
+Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
+
+**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them - don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it - don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+---
+
+**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.
+
+---
+
+## 5. 记忆与自学习
+
+遇到用户表达"记住 / 偏好 / 习惯 / 纠正"意图时，**持久化到 `MEMORY.md`**，让后续会话能复用。
+
+### 5.1 触发词
+
+当用户消息包含以下关键词或意图时，必须写入 `MEMORY.md`：
+
+| 触发词/句式 | 含义 | 写入栏目 |
+|---|---|---|
+| "记住…"、"记下…"、"帮我记住…" | 用户想持久化一条事实/偏好 | User Mem |
+| "以后不要…"、"下次别…"、"别再…" | 用户纠正某个行为，以后避免 | User Mem |
+| "下次记得…"、"以后都…"、"以后遇到…就…" | 用户指定未来的默认行为 | User Mem |
+| "我喜欢…"、"我习惯…"、"我偏好…" | 用户表达工作习惯或偏好 | User Mem |
+
+如果消息是否触发记忆有歧义，先问用户确认再写入。不要为每次对话自动记录。
+
+### 5.2 MEMORY.md 写入格式
+
+在 `MEMORY.md` 的 `## User Mem` 栏目下，按日期倒序追加。每条格式：
+
+```markdown
+### YYYY-MM-DD — <简短标题>
+- **触发词**：<用户原话>
+- **行为**：<以后应该怎么做 / 避免做什么>
+- **原因**：<用户说明的原因，如果有>
+```
+
+### 5.3 自学习：工具调用规范
+
+Claude Code 发现以下模式时，在不涉及用户隐私的前提下，自动追加到 `MEMORY.md` 的 `## 工具调用规范` 栏目：
+
+| 发现模式 | 记录内容 |
+|---|---|
+| 某工具/MCP/skill 连续 3 次以上被高频调用但每次都失败或有更优替代 | 记录：场景 → 失败原因 → 推荐替代方案 |
+| 某类代码错误反复出现在同一文件/模块（如 lint 报错、类型错误、导入错误） | 记录：错误类型 → 触发条件 → 修复模板 |
+| 某个 skill/MCP 的调用方式与最佳实践不符导致低效 | 记录：正确用法 → 避免的用法 |
+
+格式：
+
+```markdown
+### <工具名/skill名> — <问题简述>
+- **场景**：<什么情况下触发>
+- **问题**：<具体现象>
+- **方案**：<推荐做法>
+- **日期**：<首次记录日期>
+```
+
+如果同一问题已存在记录，更新其内容而非新增一条。如果新发现与旧记录矛盾，替换旧记录并标注日期。

package/templates/common/MEMORY.md

@@ -0,0 +1,35 @@
+# MEMORY.md — {{projectName}} 项目资源索引
+
+> 当前项目事实源从 `CLAUDE.md -> docs/README.md` 进入。此文件用于跨会话持久化：资源索引、用户偏好、工具调用规范。
+
+## Agents（子代理）
+
+> 待 Claude Code 从 [ECC](https://github.com/affaan-m/ECC) 初始化。
+> 初始化命令：在 Claude Code 中描述你的项目类型和语言，Claude 会自动拉取匹配的 agents。
+
+## Skills（工作流）
+
+> 待 Claude Code 从 [ECC](https://github.com/affaan-m/ECC) 或 [awesome-claude-code-config](https://github.com/Mizoreww/awesome-claude-code-config) 初始化。
+
+## Rules（代码规则）
+
+放在 `.claude/rules/ecc/` 下，由 CC 引擎自动加载：
+
+- [common.md](.claude/rules/ecc/common.md) — 通用编码规则（alwaysApply: true）
+- 语言专属规则待 Claude Code 初始化（如 python.md、typescript.md 等）
+
+## Harness（运行时）
+
+- [架构文档](docs/harness/architecture.md)
+- [Agent 工作流](docs/harness/agent-workflow.md)
+
+## User Mem
+
+> 用户偏好、习惯、纠正指令。由 CLAUDE.md §5 触发写入，日期倒序。
+> 当前无记录 — 等待用户首次"记住…"指令。
+
+## 工具调用规范
+
+> Claude Code 自学习记录：高频工具/MCP/skill 的坑、替代方案、常见错误修复模板。
+> 由 CLAUDE.md §5.3 触发写入。
+> 当前无记录 — 等待首次自动发现。

package/templates/common/SETUP.md

@@ -0,0 +1,91 @@
+# SETUP.md — 项目初始化指南
+
+> ⚠️ **临时文件** — 本文件在初始化完成后应删除：`rm SETUP.md`
+
+---
+
+## 你现在拥有了什么
+
+`npx create-harness-vibe-coding` 为你搭建了一个 **vibe-coding agentic harness** 骨架：
+
+```
+{{projectName}}/
+  CLAUDE.md              ← Agent 行为规范 + 记忆自学习系统
+  AGENTS.md              ← Coding agent 入口
+  MEMORY.md              ← 跨会话资源索引
+  docs/                  ← 架构文档（分层规则、工作流、端口合同）
+  .claude/
+    settings.json        ← 权限 + Hooks 配置
+    agents/              ← 空 — 待拉取 ECC agents
+    skills/              ← 空 — 待拉取 ECC skills
+    hooks/               ← 空 — 待配置自动化钩子
+    rules/ecc/
+      common.md          ← 通用编码规则（始终生效）
+  tests/                 ← 待初始化
+  .gitignore             ← 基础 Git 忽略规则
+```
+
+---
+
+## 下一步：用 Claude Code 初始化项目内容
+
+### Step 1 — 启动 Claude Code
+
+```bash
+claude
+```
+
+### Step 2 — 描述你的项目
+
+告诉 Claude 你的项目类型、语言和技术栈。Claude 会：
+
+1. 从 [ECC](https://github.com/affaan-m/ECC) 拉取匹配的 **agents**（如 code-reviewer、planner、security-reviewer）
+2. 从 ECC 拉取匹配的 **skills**（如 tdd-workflow、django-patterns、react-patterns）
+3. 从 ECC 拉取对应语言的 **rules**（如 python.md、typescript.md）
+4. 根据项目需要配置 **hooks**（如 PostToolUse 自动 lint、PreToolUse 安全门禁）
+
+**对话示例**：
+
+```
+你: 这是一个 Python 量化交易项目，帮我从 ECC 初始化 agents、skills 和 rules
+你: 这是一个 React + TypeScript 前端项目，需要 TDD workflow
+你: 这是一个 Go 微服务项目，帮我配置对应的代码审查和测试 skills
+```
+
+### Step 3 — 可选：安装 Superpowers 强化工程纪律
+
+```bash
+# 在 Claude Code 中运行
+/plugin install superpowers@claude-plugins-official
+```
+
+Superpowers 提供：brainstorming → writing-plans → TDD → code-review 的完整闭环。
+
+### Step 4 — 初始化完成后
+
+```bash
+rm SETUP.md
+```
+
+---
+
+## 参考资源
+
+| 资源 | 地址 | 用途 |
+|------|------|------|
+| ECC | https://github.com/affaan-m/ECC | Agents / Skills / Rules 主仓库 |
+| awesome-claude-code-config | https://github.com/Mizoreww/awesome-claude-code-config | 多语言规则 + 自学习配置 |
+| Superpowers | https://github.com/obra/superpowers | 工程纪律插件 |
+| claude-toolbox | https://github.com/serpro69/claude-toolbox | 多语言技能工具包 |
+
+---
+
+## 自定义
+
+- **CLAUDE.md** — 可按项目需求修改行为规范
+- **.claude/settings.json** — 按需调整权限和 hooks
+- **.claude/rules/ecc/** — 语言规则由 Claude Code 自动添加
+
+---
+
+> 本项目由 `create-harness-vibe-coding` 生成。保留 MIT 许可。