specline 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zhouyushun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,161 @@
+# Specline
+
+面向 Cursor IDE 的 **Spec 驱动 AI 编码流水线**，内置确定性质量门禁。
+
+一句话需求 → 自动走完 编写规格 → 编码 → 审查 → 测试 → 归档 全流程：
+
+```
+/specline-pipeline "实现用户登录功能"
+```
+
+## 它能做什么
+
+```
+自然语言需求 → Spec → 审核 → 编码 → 审查 → 测试 → 归档
+                ↑       ↑      ↑      ↑      ↑      ↑
+           spec-    spec-  前后端  code-  单元/   ✓ 完成
+          creator  reviewer  并行  reviewer  集成/
+                                          E2E
+```
+
+每个阶段都经过 **确定性门禁校验** —— 用 `grep`、`jq`、编译器退出码、测试退出码判断通过与否。**质量判断零 LLM 参与**。
+
+## 核心特性
+
+- **需求驱动**：自然语言 → 结构化规格文档（Requirements + Scenarios + WHEN/THEN）
+- **并行编码**：自动按前端/后端拆分任务，同批次并发派发 Coding Agent
+- **确定性门禁**：每个阶段用 Shell 脚本的退出码判定是否通过，不做模糊判断
+- **黑盒测试**：测试 Agent 只看 Spec 文档，不能读取任何实现源码
+- **断点续跑**：随时中断，下次从最后一个可信门禁自动恢复（tasks.md 的 `[x]`/`[ ]` 标记进度）
+- **人机协作**：3 个人工检查点——Spec 确认、Review 可选复核、归档确认
+- **安全 Hook**：自动拦截危险 Shell 命令（如 `rm -rf`、`curl|bash`）+ 代码变更后自动格式化
+- **零外部依赖**：不依赖 OpenSpec CLI，全部功能自包含
+
+## 快速开始
+
+```bash
+# 全局安装
+npm install -g specline
+
+# 在项目中初始化
+cd my-project
+specline init
+
+# 或者用 npx（无需安装）
+npx specline init
+```
+
+初始化后项目会获得完整的流水线基础设施：
+
+```
+my-project/
+├── .cursor/
+│   ├── agents/          ← 7 个 Specline Agent 定义
+│   ├── commands/        ← 2 个 Slash 命令入口
+│   ├── skills/          ← 5 个 Skill 指令
+│   ├── hooks/           ← 4 个 Gate/Hook 脚本
+│   └── hooks.json       ← Cursor Hook 配置
+├── specline/            ← 运行时目录
+│   ├── config.yaml
+│   ├── changes/         ← 变更目录
+│   │   └── archive/     ← 归档目录
+│   └── specs/           ← 主规格目录
+└── .specline-config.yaml
+```
+
+然后在 Cursor 中输入：
+
+```
+/specline-pipeline "添加 JWT 用户认证"
+```
+
+开始编码前先探索思路：
+
+```
+/specline-explore
+```
+
+## 流水线阶段
+
+```
+PHASE 1: SPEC（规格）
+  specline-spec-creator 生成 4 个规划文件
+    ├── proposal.md    — 需求提案（What/Why/Scope）
+    ├── specs/*/spec.md — 功能规格（Requirements/Scenarios/WHEN-THEN）
+    ├── design.md      — 技术设计（架构/数据流/决策）
+    └── tasks.md       — 任务清单（Type/Depends/Covers/Files + [ ] 进度标记）
+  → specline-spec-reviewer 审核
+  → Gate: grep + jq 格式校验
+  → 🟡 人工确认 Spec 和任务规划
+
+PHASE 2: CODING（编码）
+  解析 tasks.md → 按依赖 DAG 分层 → 同批次前后端 Agent 并发
+  每完成一个任务，[ ] 自动标记为 [x]
+  → Gate: 编译检查（tsc --noEmit / python -m compileall）
+
+PHASE 3: REVIEW（审查）
+  specline-code-reviewer 审查代码质量、安全性、可维护性
+  → Gate: Lint 检查 + code-review.json error 计数
+
+PHASE 4: TEST（测试）
+  单元测试 → 集成测试 → E2E 测试（黑盒，只看 Spec）
+  → 失败自动分析：测试写错了 / 代码写错了 / Spec 模糊
+  → 自动重试最多 2 次
+
+PHASE 5: ARCHIVE（归档）
+  → 🟡 人工确认归档
+  → delta specs 合并到主规格目录
+  → 按日期归档到 specline/changes/archive/
+  ✅ 完成
+```
+
+## 架构
+
+```
+/specline-pipeline       ← 你输入这个
+    │
+    ▼
+specline-pipeline SKILL  ← 编排层（读状态、派发 Agent、调 Gate）
+    │
+┌───┼──────────────────┬──────────────────────┐
+▼   ▼                  ▼                      ▼
+7 个子 Agent      specline-pipeline-     Cursor Hooks
+（创造性工作）      gate.sh              （安全网）
+                  （确定性门禁）
+```
+
+## 子 Agent 列表
+
+| Agent | 职责 |
+|-------|------|
+| `specline-spec-creator` | 根据自然语言需求，基于内联模板直接生成 proposal/design/tasks/spec 四个文件 |
+| `specline-spec-reviewer` | 审核规格的完整性、一致性和覆盖度 |
+| `specline-frontend-dev` | UI 组件、页面、样式、交互逻辑（单个任务级别） |
+| `specline-backend-dev` | API 端点、数据模型、业务逻辑（单个任务级别） |
+| `specline-code-reviewer` | 代码质量、安全性、可维护性审查 |
+| `specline-test-writer` | 黑盒测试编写——只能看 Spec，不能读源码 |
+| `specline-test-runner` | 执行测试并分类失败原因（测试问题/代码问题/Spec 模糊） |
+
+## 确定性门禁
+
+每个门禁都是 Shell 脚本，`exit 0` = 通过，`exit 1` = 失败：
+
+| 门禁 | 检查内容 |
+|------|---------|
+| Spec | `grep` 检查 Purpose/Requirements/Scenarios 章节完整性、WHEN/THEN 配对 |
+| Build | `tsc --noEmit` / `python -m compileall` 编译检查 |
+| Lint | `ruff` / `eslint` 退出码 + code-review.json 中 error 数量 |
+| Test | 测试框架退出码 + 覆盖率阈值 |
+| Archive | 归档目录结构 + 必要文件完整性 |
+
+## 环境要求
+
+- **Cursor IDE**（支持 hooks 和 skills）
+- **jq**（Gate 脚本 JSON 处理）
+  - macOS 预装
+  - Linux: `apt install jq`
+  - Windows: `choco install jq`
+
+## License
+
+MIT

package/cli.mjs

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+
+import { existsSync, mkdirSync, readdirSync, copyFileSync, writeFileSync } from 'fs';
+import { join, dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = join(__dirname, 'templates');
+const VERSION = '1.0.0';
+
+function log(msg) {
+  console.log(msg);
+}
+
+function warn(msg) {
+  console.log(`\x1b[33m⚠️  ${msg}\x1b[0m`);
+}
+
+function success(msg) {
+  console.log(`\x1b[32m✅ ${msg}\x1b[0m`);
+}
+
+function error(msg) {
+  console.error(`\x1b[31m❌ ${msg}\x1b[0m`);
+}
+
+function copyDirRecursive(src, dest) {
+  if (!existsSync(dest)) {
+    mkdirSync(dest, { recursive: true });
+  }
+  const entries = readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = join(src, entry.name);
+    const destPath = join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirRecursive(srcPath, destPath);
+    } else {
+      copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function cmd_init(targetPath) {
+  const cwd = process.cwd();
+  const target = resolve(cwd, targetPath || '.');
+
+  if (!existsSync(target)) {
+    error(`目标路径不存在: ${target}`);
+    process.exit(1);
+  }
+
+  const configFile = join(target, '.specline-config.yaml');
+  const forceMode = process.argv.includes('--force') || process.argv.includes('-f');
+
+  if (existsSync(configFile) && !forceMode) {
+    warn('Specline 已在此项目中初始化。使用 --force 强制覆盖。');
+    process.exit(0);
+  }
+
+  // 检测 hooks.json 冲突
+  const hooksJsonDest = join(target, '.cursor', 'hooks.json');
+  if (existsSync(hooksJsonDest)) {
+    const backupPath = hooksJsonDest + '.bak';
+    copyFileSync(hooksJsonDest, backupPath);
+    warn('已备份原有 hooks.json → .cursor/hooks.json.bak');
+  }
+
+  // 创建目录结构
+  const dirs = [
+    '.cursor/agents',
+    '.cursor/commands',
+    '.cursor/skills',
+    '.cursor/hooks',
+    'specline/changes/archive',
+    'specline/specs',
+  ];
+
+  for (const dir of dirs) {
+    const fullDir = join(target, dir);
+    if (!existsSync(fullDir)) {
+      mkdirSync(fullDir, { recursive: true });
+    }
+  }
+
+  // 从 templates/ 复制文件
+  if (!existsSync(TEMPLATES_DIR)) {
+    error(`templates/ 目录不存在: ${TEMPLATES_DIR}`);
+    process.exit(1);
+  }
+
+  copyDirRecursive(TEMPLATES_DIR, target);
+
+  // 统计各类文件数量
+  function countFiles(dir) {
+    let count = 0;
+    if (!existsSync(dir)) return 0;
+    try {
+      const entries = readdirSync(dir, { withFileTypes: true, recursive: true });
+      for (const entry of entries) {
+        if (entry.isFile()) count++;
+      }
+    } catch (_) {}
+    return count;
+  }
+
+  const agentsCount = countFiles(join(target, '.cursor', 'agents'));
+  const commandsCount = countFiles(join(target, '.cursor', 'commands'));
+  const skillsCount = countFiles(join(target, '.cursor', 'skills'));
+  const hooksCount = countFiles(join(target, '.cursor', 'hooks'));
+
+  // 写入初始化配置
+  const initConfig = `# Specline 项目配置
+version: "${VERSION}"
+initialized_at: "${new Date().toISOString()}"
+`;
+  writeFileSync(configFile, initConfig, 'utf-8');
+
+  success('Specline 初始化完成');
+  log(`📁 文件: ${commandsCount} commands, ${skillsCount} skills, ${agentsCount} agents, ${hooksCount} hooks`);
+  log('');
+  log('🚀 试试在 Cursor 中输入:');
+  log('   /specline-pipeline "你的第一个需求"');
+  log('   /specline-explore');
+
+  process.exit(0);
+}
+
+function cmd_version() {
+  log(`specline v${VERSION}`);
+  process.exit(0);
+}
+
+function cmd_help() {
+  log(`specline v${VERSION} — Spec-driven AI coding pipeline for Cursor IDE
+
+用法:
+  specline init [path]        在指定路径初始化流水线基础设施
+  specline init --force       强制覆盖已有配置
+  specline --version, -v      显示版本号
+  specline --help, -h         显示此帮助信息
+
+示例:
+  specline init               在当前目录初始化
+  specline init ./my-project  在指定目录初始化
+  npx specline init           无需全局安装即可使用
+`);
+  process.exit(0);
+}
+
+// 入口
+const [,, command, ...args] = process.argv;
+
+switch (command) {
+  case 'init': {
+    // 过滤出 --force/-f 之外的真实路径参数
+    const pathArg = args.filter(a => a !== '--force' && a !== '-f')[0];
+    cmd_init(pathArg);
+    break;
+  }
+  case '--version':
+  case '-v':
+    cmd_version();
+    break;
+  case '--help':
+  case '-h':
+  default:
+    cmd_help();
+    break;
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "specline",
+  "version": "1.0.0",
+  "description": "Spec-driven AI coding pipeline with deterministic quality gates for Cursor IDE",
+  "bin": {
+    "specline": "./cli.mjs"
+  },
+  "files": [
+    "cli.mjs",
+    "templates/"
+  ],
+  "keywords": [
+    "cursor",
+    "specline",
+    "spec-driven",
+    "ai-coding",
+    "pipeline",
+    "agent-orchestration",
+    "deterministic-gates",
+    "dev-pipeline"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/RayChou1221/specline"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/templates/.cursor/agents/specline-backend-dev.md

@@ -0,0 +1,47 @@
+---
+name: specline-backend-dev
+description: 根据 Spec 编写后端代码（API 端点、数据模型、业务逻辑、CLI 命令）。只操作后端相关文件。支持 task-aware 模式——接收单个任务，只修改该任务涉及的文件。
+---
+
+你是后端开发专家。你通过 `/dev-pipeline` 编排系统接收**单个编码任务**。
+
+## 任务上下文
+
+你在流水线的 Coding 阶段被调用。每次调用时，主 Agent 会传递以下上下文：
+
+1. **当前任务**：从 `tasks.md` 中提取的单一任务描述（Type: backend 的任务）
+2. **Spec 文档**：`specline/changes/<change-name>/specs/<capability>/spec.md`
+3. **Design 文档**：`specline/changes/<change-name>/design.md`
+4. **全部任务列表**：`specline/changes/<change-name>/tasks.md`（了解其他任务的范围）
+
+## 工作方式
+
+1. 理解当前任务的范围和边界——只实现本任务描述的 API/模型/逻辑功能
+2. 阅读 Spec 中与当前任务相关的后端需求
+3. 确认 design.md 中的技术决策（架构模式、数据流、错误处理策略等）
+4. 编写代码，遵循项目现有代码风格和架构模式
+5. 完成后输出变更文件列表
+6. **完成后必须将 `specline/changes/<change-name>/tasks.md` 中本任务标题的 `[ ]` 改为 `[x]`**（方便流水线断点续跑）
+
+## 约束
+
+- 只操作本任务涉及的后端文件（.py 后端代码、数据模型、API 路由、CLI 命令等）
+- 不修改前端 UI 组件和样式
+- 不修改其他任务负责的文件
+- 与其他任务约定的接口（API 端点、数据模型字段等）必须严格遵守
+- 保持与现有代码风格一致
+- 确保错误处理和日志记录完整
+
+## 产出报告
+
+完成后输出 JSON 到 `.cursor/tmp/task-<task-id>-result.json`：
+
+```json
+{
+  "task_id": "<task-id>",
+  "type": "backend",
+  "status": "completed",
+  "files_changed": ["server/models.py", "server/routes/api.py"],
+  "summary": "实现了 Agent 数据模型和 API 端点"
+}
+```

package/templates/.cursor/agents/specline-code-reviewer.md

@@ -0,0 +1,51 @@
+---
+name: specline-code-reviewer
+description: 审查代码变更的质量、安全性和最佳实践。产出结构化的 code-review.json，区分 error（必须修复）和 warning（建议改进）。利用 tasks.md 的 Covers 追溯链定位问题。
+---
+
+你是代码审查专家。审查最近的代码变更，产出结构化审查结果。
+
+## 审查维度
+
+1. **正确性**：逻辑是否正确，边界条件是否处理
+2. **安全性**：是否有注入风险、密钥泄露、权限漏洞
+3. **性能**：是否有明显性能问题（N+1 查询、未释放资源等）
+4. **可维护性**：命名是否清晰、是否有重复代码、模块划分是否合理
+5. **错误处理**：异常是否被妥善捕获和处理
+6. **测试友好**：代码是否易于测试
+
+## 工作方式
+
+1. 查看 git diff 获取变更文件列表
+2. 对照 `specline/changes/<change-name>/tasks.md` 中的 `Covers` 追溯链，知道每个文件属于哪个任务、覆盖哪个 Requirement
+3. 逐一审查变更代码
+4. 每个发现标记 severity：`error`（必须修复）或 `warning`（建议改进）
+5. 每个发现标注 `covers`：对应的 Requirement 名称（从 tasks.md 的 Covers 中获取）
+6. 每个发现标注 `task_id`：对应的任务编号
+
+## 输出格式
+
+产出 `code-review.json`：
+
+```json
+{
+  "findings": [
+    {
+      "severity": "error",
+      "file": "agent/daemon.py",
+      "line": 45,
+      "task_id": "3",
+      "covers": "Requirement: 守护进程管理",
+      "message": "未处理 WebSocket 连接超时异常，可能导致守护进程崩溃"
+    },
+    {
+      "severity": "warning",
+      "file": "server/models.py",
+      "line": 12,
+      "task_id": "1",
+      "covers": "Requirement: 数据模型",
+      "message": "建议为 Agent 表添加索引以优化按状态查询的性能"
+    }
+  ]
+}
+```

package/templates/.cursor/agents/specline-frontend-dev.md

@@ -0,0 +1,47 @@
+---
+name: specline-frontend-dev
+description: 根据 Spec 编写前端代码（UI 组件、页面、样式、交互逻辑）。加载 frontend-design skill 确保设计质量。只操作前端相关文件。支持 task-aware 模式——接收单个任务，只修改该任务涉及的文件。
+---
+
+你是前端开发专家。你通过 `/dev-pipeline` 编排系统接收**单个编码任务**。
+
+## 任务上下文
+
+你在流水线的 Coding 阶段被调用。每次调用时，主 Agent 会传递以下上下文：
+
+1. **当前任务**：从 `tasks.md` 中提取的单一任务描述（Type: frontend 的任务）
+2. **Spec 文档**：`specline/changes/<change-name>/specs/<capability>/spec.md`
+3. **Design 文档**：`specline/changes/<change-name>/design.md`
+4. **全部任务列表**：`specline/changes/<change-name>/tasks.md`（了解其他任务的范围）
+
+## 工作方式
+
+1. 理解当前任务的范围和边界——只实现本任务描述的 UI/样式/交互功能
+2. 阅读 Spec 中与当前任务相关的前端需求
+3. 确认 design.md 中的技术决策（组件库、样式方案、路由设计等）
+4. 编写代码，优先加载 `frontend-design` skill 确保设计质量
+5. 完成后输出变更文件列表
+6. **完成后必须将 `specline/changes/<change-name>/tasks.md` 中本任务标题的 `[ ]` 改为 `[x]`**（方便流水线断点续跑）
+
+## 约束
+
+- 只操作本任务涉及的前端文件（.tsx, .jsx, .css, .html, 组件文件等）
+- 不修改后端 API、数据模型、业务逻辑
+- 不修改其他任务负责的文件
+- 与其他任务约定的接口（API 格式、Props 类型等）必须严格遵守
+- 保持代码风格一致
+- 确保组件可用的默认状态（无数据时不崩溃）
+
+## 产出报告
+
+完成后输出 JSON 到 `.cursor/tmp/task-<task-id>-result.json`：
+
+```json
+{
+  "task_id": "<task-id>",
+  "type": "frontend",
+  "status": "completed",
+  "files_changed": ["src/components/Header.tsx", "src/styles/main.css"],
+  "summary": "实现了 Dashboard 页面和 Header 组件"
+}
+```