@alenfitz/spec-copilot 1.0.0

package/README.md

@@ -0,0 +1,112 @@
+# @alenfitz/spec-copilot
+
+**Spec-Driven Development Framework** — One package, six AI coding tools. Turn AI coding from "black-box YOLO" into "white-box step-by-step."
+
+[中文文档](./README.zh-CN.md)
+
+---
+
+## Supported Tools
+
+| Tool | Prompt File | Commands |
+|------|-----------|----------|
+| **opencode** | `AGENTS.md` | `.opencode/commands/` (native) |
+| **Claude Code** | `CLAUDE.md` | `.claude/commands/` (native) |
+| **Cursor** | `.cursor/rules/spec-copilot.mdc` | Prompt routing |
+| **Windsurf** | `.windsurf/rules/spec-copilot.md` | Prompt routing |
+| **GitHub Copilot** | `.github/copilot-instructions.md` | Prompt routing |
+| **Cline** | `.clinerules/spec-copilot.md` | Prompt routing |
+
+## Quick Start
+
+```bash
+# Install — specify your tool
+npx @alenfitz/spec-copilot install --tool cursor
+npx @alenfitz/spec-copilot install --tool claude-code
+npx @alenfitz/spec-copilot install --tool windsurf
+# ... any of: opencode, claude-code, cursor, windsurf, copilot, cline
+
+# Verify
+npx @alenfitz/spec-copilot doctor
+```
+
+The framework auto-detects your tool on subsequent commands (`update`, `doctor`, etc.).
+
+## How It Works
+
+1. **Spec First (No Spec, No Code)** — AI evaluates complexity, asks questions, generates spec in segments. No confirmed spec, no code written.
+2. **Task Rhythm** — AI completes one atomic task, shows proof, commits immediately, then **waits for you to say "continue."**
+3. **Knowledge Flywheel** — Pitfalls are logged and archived into a tag-indexed knowledge base. Next requirement reads past experience.
+
+## Commands
+
+| Command | When | Output |
+|---------|------|--------|
+| `/spec:init` | First time setup | Fills `rules/project-context.md` |
+| `/spec:bootstrap` | New empty project | Tech stack selection + scaffolding |
+| `/spec:propose <req>` | New requirement | `spec.md` (+ `tasks.md` if complex) |
+| `/spec:flow <req>` | Auto mode (simple/medium) | Full pipeline: propose → archive |
+| `/spec:apply <name>` | After spec confirmed | Code committed task by task |
+| `/spec:smoke <name>` | After /spec:apply | Build + API smoke test |
+| `/spec:review <name>` | After /spec:smoke | Spec compliance + code quality report |
+| `/spec:fix <name>` | After review issues | Fix commits + doc sync |
+| `/spec:archive <name>` | After review passes | Knowledge captured, merge prompt |
+| `/spec:hotfix <desc>` | Production incident | Minimal fix on hotfix branch |
+| `/spec:test <name>` | Need automated tests | Test code + run results |
+
+## CLI Commands
+
+```bash
+npx @alenfitz/spec-copilot install --tool <name>    # Install framework
+npx @alenfitz/spec-copilot update [--force]          # Upgrade framework
+npx @alenfitz/spec-copilot gate <name> <phase>       # Phase gate check
+npx @alenfitz/spec-copilot lint <name>               # Spec completeness check
+npx @alenfitz/spec-copilot doctor                    # Health check
+npx @alenfitz/spec-copilot uninstall --confirm       # Remove framework
+```
+
+## What Gets Installed
+
+```
+your-project/
+├── <tool-specific prompt file>        ← AI reads this
+├── <tool-specific commands/>          ← Native commands (if supported)
+│
+└── spec_copilot/
+    ├── commands/                      ← 11 command definitions
+    ├── rules/
+    │   ├── coding-style.md            ← Universal coding standards
+    │   ├── security.md                ← Security red lines
+    │   ├── project-context.md         ← Your project's tech context
+    │   └── domain-rules.md            ← Business rules (you fill this)
+    ├── stack-adapters/
+    │   ├── _template.md               ← Template for new tech stacks
+    │   └── spring-boot-vue3.md        ← Built-in adapter (example)
+    ├── knowledge/index.md             ← Tag-indexed knowledge base
+    ├── changes/templates/             ← spec.md / tasks.md / log.md
+    ├── archives/                      ← Completed requirements
+    └── scripts/                       ← Lint, gate, hook scripts
+```
+
+## Complexity Tiers
+
+| Tier | Criteria | What's Required |
+|------|----------|----------------|
+| 🟢 Simple | No API/schema/core flow/new dependency changes | Direct conversation, no spec |
+| 🟡 Medium | New APIs, non-core schema, new dependency | Spec (2-segment confirmation) |
+| 🔴 Complex | New subsystem, core flow, core schema, concurrency | Spec + tasks + knowledge |
+
+## Upgrade Safety
+
+- **Overwritten**: coding-style.md, security.md, templates, scripts, commands, built-in adapters
+- **Skipped by default**: prompt file (use `--force`)
+- **Never touched**: project-context.md, domain-rules.md, knowledge/, changes/, archives/, custom adapters
+
+## Related Packages
+
+- [`@alenfitz/opencode-copilot`](https://www.npmjs.com/package/@alenfitz/opencode-copilot) — opencode-only version
+- [`@alenfitz/spec-driven-dev`](https://www.npmjs.com/package/@alenfitz/spec-driven-dev) — Claude Code-only version (legacy)
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,112 @@
+# @alenfitz/spec-copilot
+
+**渐进式 Spec 编码框架** — 一个包，六种 AI 编码工具。让 AI 编码从"黑盒一把梭"变成"白盒分步推进"。
+
+[English](./README.md)
+
+---
+
+## 支持工具
+
+| 工具 | 提示词文件 | 命令方式 |
+|------|-----------|---------|
+| **opencode** | `AGENTS.md` | `.opencode/commands/`（原生） |
+| **Claude Code** | `CLAUDE.md` | `.claude/commands/`（原生） |
+| **Cursor** | `.cursor/rules/spec-copilot.mdc` | Prompt 路由 |
+| **Windsurf** | `.windsurf/rules/spec-copilot.md` | Prompt 路由 |
+| **GitHub Copilot** | `.github/copilot-instructions.md` | Prompt 路由 |
+| **Cline** | `.clinerules/spec-copilot.md` | Prompt 路由 |
+
+## 快速开始
+
+```bash
+# 安装 — 指定你的工具
+npx @alenfitz/spec-copilot install --tool cursor
+npx @alenfitz/spec-copilot install --tool claude-code
+npx @alenfitz/spec-copilot install --tool windsurf
+# 可选: opencode, claude-code, cursor, windsurf, copilot, cline
+
+# 验证安装
+npx @alenfitz/spec-copilot doctor
+```
+
+后续命令（`update`、`doctor` 等）自动识别已安装的工具。
+
+## 核心理念
+
+1. **Spec 先行（No Spec, No Code）** — AI 评估复杂度、逐条澄清、分段生成 spec，确认才写代码。
+2. **Task 节奏可控** — AI 完成一个原子任务就停下来，展示验证证据，立即 commit，等你说"继续"才推进。
+3. **知识飞轮** — 每个需求的踩坑记录归档到带 tag 分类的知识库，下个需求自动读取。
+
+## 命令速查
+
+| 命令 | 何时用 | 产出 |
+|------|-------|------|
+| `/spec:init` | 首次接入项目 | 填充 `rules/project-context.md` |
+| `/spec:bootstrap` | 新空项目 | 栈选型 + 脚手架搭建 |
+| `/spec:propose <需求>` | 有新需求 | `spec.md`（复杂需求 + `tasks.md`） |
+| `/spec:flow <需求>` | 全自动模式（🟢/🟡） | 完整流水线：propose → archive |
+| `/spec:apply <变更名>` | spec 确认后 | 逐 task 提交的代码 |
+| `/spec:smoke <变更名>` | /spec:apply 完成后 | 编译 + 接口冒烟报告 |
+| `/spec:review <变更名>` | /spec:smoke 通过后 | Spec 合规 + 代码质量审查报告 |
+| `/spec:fix <变更名>` | review 有问题 | 修复 commit + 文档同步 |
+| `/spec:archive <变更名>` | review 通过后 | 知识沉淀 + 分支合并提示 |
+| `/spec:hotfix <描述>` | 线上故障 | 最小修复 + hotfix 分支 |
+| `/spec:test <变更名>` | 补自动化测试 | 测试代码 + 运行报告 |
+
+## CLI 命令
+
+```bash
+npx @alenfitz/spec-copilot install --tool <name>    # 安装框架
+npx @alenfitz/spec-copilot update [--force]          # 升级框架
+npx @alenfitz/spec-copilot gate <变更名> <phase>      # 阶段门禁检查
+npx @alenfitz/spec-copilot lint <变更名>              # Spec 完整性检查
+npx @alenfitz/spec-copilot doctor                    # 检查安装状态
+npx @alenfitz/spec-copilot uninstall --confirm       # 移除框架
+```
+
+## 安装后的目录结构
+
+```
+你的项目/
+├── <工具专属提示词文件>               ← AI 读取
+├── <工具专属命令目录/>               ← 原生命令（如支持）
+│
+└── spec_copilot/
+    ├── commands/                      ← 11 个命令定义
+    ├── rules/
+    │   ├── coding-style.md            ← 编码通用规范
+    │   ├── security.md                ← 安全红线
+    │   ├── project-context.md         ← 项目技术上下文（/spec:init 填充）
+    │   └── domain-rules.md            ← 业务领域规则（你来填）
+    ├── stack-adapters/
+    │   ├── _template.md               ← 新栈适配模板
+    │   └── spring-boot-vue3.md        ← 内置适配（示例）
+    ├── knowledge/index.md             ← 带 tag 索引的知识库
+    ├── changes/templates/             ← spec.md / tasks.md / log.md 模板
+    ├── archives/                      ← 已归档的需求
+    └── scripts/                       ← Lint、门禁、Hook 脚本
+```
+
+## 复杂度分级
+
+| 级别 | 判定标准（按影响面） | 需要什么 |
+|------|-----------------|---------|
+| 🟢 简单 | 不改 API / 不改表 / 不改核心流程 / 不引入新依赖 | 直接对话 |
+| 🟡 中等 | 新增接口 / 改表非核心字段 / 新依赖 | spec（两段确认） |
+| 🔴 复杂 | 新子系统 / 核心流程 / 核心表结构 / 并发事务 | spec + tasks + knowledge |
+
+## 升级安全性
+
+- **会覆盖**：coding-style.md、security.md、模板、脚本、命令、内置栈适配
+- **默认跳过**：提示词文件（使用 `--force` 覆盖）
+- **绝不覆盖**：project-context.md、domain-rules.md、knowledge/、changes/、archives/、自定义栈适配
+
+## 相关包
+
+- [`@alenfitz/opencode-copilot`](https://www.npmjs.com/package/@alenfitz/opencode-copilot) — opencode 专属版
+- [`@alenfitz/spec-driven-dev`](https://www.npmjs.com/package/@alenfitz/spec-driven-dev) — Claude Code 专属版（旧版）
+
+## License
+
+MIT

package/adapters/index.js

@@ -0,0 +1,218 @@
+/**
+ * Tool adapters — 每个 AI 编码工具的适配配置
+ *
+ * 每个 adapter 定义：
+ *   - promptPath: 提示词文件相对项目根目录的路径
+ *   - commandsDir: 原生命令目录（null = 无原生命令支持）
+ *   - detect(projectRoot): 自动检测该工具是否在使用
+ *   - formatPrompt(content): 将通用 prompt 转换为工具专属格式
+ *   - formatCommand(content, meta): 将通用命令转换为工具专属格式
+ *   - cleanupPaths: uninstall 时需清理的路径（相对项目根）
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ─── 命令路由模板（无原生命令的工具追加到 prompt 末尾） ───────
+
+function buildCommandRoutingSection() {
+  return `
+
+---
+
+## 命令路由
+
+当用户输入以下命令时，读取对应文件并按其指令执行：
+
+| 命令 | 读取文件 |
+|------|---------|
+| \`/spec:init\` | \`spec_copilot/commands/spec:init.md\` |
+| \`/spec:bootstrap\` | \`spec_copilot/commands/spec:bootstrap.md\` |
+| \`/spec:propose <需求>\` | \`spec_copilot/commands/spec:propose.md\` |
+| \`/spec:flow <需求>\` | \`spec_copilot/commands/spec:flow.md\` |
+| \`/spec:apply <变更名>\` | \`spec_copilot/commands/spec:apply.md\` |
+| \`/spec:smoke <变更名>\` | \`spec_copilot/commands/spec:smoke.md\` |
+| \`/spec:review <变更名>\` | \`spec_copilot/commands/spec:review.md\` |
+| \`/spec:fix <变更名>\` | \`spec_copilot/commands/spec:fix.md\` |
+| \`/spec:test <变更名>\` | \`spec_copilot/commands/spec:test.md\` |
+| \`/spec:archive <变更名>\` | \`spec_copilot/commands/spec:archive.md\` |
+| \`/spec:hotfix <描述>\` | \`spec_copilot/commands/spec:hotfix.md\` |
+
+用户输入命令后，**立即**读取对应文件并执行，不需要再次确认。
+将 \`<需求>\`、\`<变更名>\`、\`<描述>\` 替换为用户在命令后提供的参数。
+`;
+}
+
+// ─── Adapters ───────────────────────────────────────────────
+
+const adapters = {
+
+  // ─── opencode ────────────────────────────────────────────
+  opencode: {
+    name: 'opencode',
+    displayName: 'opencode',
+    description: 'opencode CLI (github.com/opencode-ai/opencode)',
+    promptPath: 'AGENTS.md',
+    commandsDir: '.opencode/commands',
+    hasNativeCommands: true,
+
+    detect(projectRoot) {
+      return fs.existsSync(path.join(projectRoot, '.opencode')) ||
+             fs.existsSync(path.join(projectRoot, 'opencode.json'));
+    },
+
+    formatPrompt(content) {
+      return content;
+    },
+
+    formatCommand(content, _meta) {
+      return content; // opencode uses same format as our command files
+    },
+
+    cleanupPaths: ['AGENTS.md', '.opencode/commands'],
+  },
+
+  // ─── Claude Code ─────────────────────────────────────────
+  'claude-code': {
+    name: 'claude-code',
+    displayName: 'Claude Code',
+    description: 'Claude Code CLI (Anthropic)',
+    promptPath: 'CLAUDE.md',
+    commandsDir: '.claude/commands',
+    hasNativeCommands: true,
+
+    detect(projectRoot) {
+      return fs.existsSync(path.join(projectRoot, '.claude')) ||
+             fs.existsSync(path.join(projectRoot, 'CLAUDE.md'));
+    },
+
+    formatPrompt(content) {
+      return content;
+    },
+
+    formatCommand(content, _meta) {
+      return content; // Claude Code uses same frontmatter format
+    },
+
+    cleanupPaths: ['CLAUDE.md', '.claude/commands'],
+  },
+
+  // ─── Cursor ──────────────────────────────────────────────
+  cursor: {
+    name: 'cursor',
+    displayName: 'Cursor',
+    description: 'Cursor IDE (.cursor/rules/*.mdc)',
+    promptPath: '.cursor/rules/spec-copilot.mdc',
+    commandsDir: null, // commands go to spec_copilot/commands/
+    hasNativeCommands: false,
+
+    detect(projectRoot) {
+      return fs.existsSync(path.join(projectRoot, '.cursor')) ||
+             fs.existsSync(path.join(projectRoot, '.cursorrules'));
+    },
+
+    formatPrompt(content) {
+      const frontmatter = [
+        '---',
+        'description: "Spec-Driven Development Framework — AI 编码协作规范"',
+        'alwaysApply: true',
+        '---',
+        '',
+      ].join('\n');
+      return frontmatter + content + buildCommandRoutingSection();
+    },
+
+    formatCommand(content, _meta) {
+      return content; // stored in spec_copilot/commands/, not tool-specific
+    },
+
+    cleanupPaths: ['.cursor/rules/spec-copilot.mdc'],
+  },
+
+  // ─── Windsurf ────────────────────────────────────────────
+  windsurf: {
+    name: 'windsurf',
+    displayName: 'Windsurf',
+    description: 'Windsurf IDE (.windsurf/rules/)',
+    promptPath: '.windsurf/rules/spec-copilot.md',
+    commandsDir: null,
+    hasNativeCommands: false,
+
+    detect(projectRoot) {
+      return fs.existsSync(path.join(projectRoot, '.windsurf')) ||
+             fs.existsSync(path.join(projectRoot, '.windsurfrules'));
+    },
+
+    formatPrompt(content) {
+      return content + buildCommandRoutingSection();
+    },
+
+    formatCommand(content, _meta) {
+      return content;
+    },
+
+    cleanupPaths: ['.windsurf/rules/spec-copilot.md'],
+  },
+
+  // ─── GitHub Copilot ──────────────────────────────────────
+  copilot: {
+    name: 'copilot',
+    displayName: 'GitHub Copilot',
+    description: 'GitHub Copilot (.github/copilot-instructions.md)',
+    promptPath: '.github/copilot-instructions.md',
+    commandsDir: null,
+    hasNativeCommands: false,
+
+    detect(projectRoot) {
+      return fs.existsSync(path.join(projectRoot, '.github', 'copilot-instructions.md'));
+    },
+
+    formatPrompt(content) {
+      return content + buildCommandRoutingSection();
+    },
+
+    formatCommand(content, _meta) {
+      return content;
+    },
+
+    cleanupPaths: ['.github/copilot-instructions.md'],
+  },
+
+  // ─── Cline ───────────────────────────────────────────────
+  cline: {
+    name: 'cline',
+    displayName: 'Cline',
+    description: 'Cline VSCode extension (.clinerules/)',
+    promptPath: '.clinerules/spec-copilot.md',
+    commandsDir: null,
+    hasNativeCommands: false,
+
+    detect(projectRoot) {
+      return fs.existsSync(path.join(projectRoot, '.clinerules')) ||
+             fs.existsSync(path.join(projectRoot, '.cline'));
+    },
+
+    formatPrompt(content) {
+      return content + buildCommandRoutingSection();
+    },
+
+    formatCommand(content, _meta) {
+      return content;
+    },
+
+    cleanupPaths: ['.clinerules/spec-copilot.md'],
+  },
+
+};
+
+/** 自动检测项目中使用的工具 */
+function detectTools(projectRoot) {
+  return Object.values(adapters).filter(a => a.detect(projectRoot));
+}
+
+/** 获取所有支持的工具名 */
+function supportedTools() {
+  return Object.keys(adapters);
+}
+
+module.exports = { adapters, detectTools, supportedTools, buildCommandRoutingSection };