specline 1.3.4 → 2.0.0

package/core/skills/specline-propose/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: specline-propose
+description: >-
+  生成 Spec 规划文件（proposal/design/tasks/spec）。根据自然语言需求，
+  直接按内联模板创建全部 Artifact，不依赖外部 CLI。
+---
+
+## Layer 1: TL;DR
+
+> **一句话**：根据自然语言需求生成完整的 Spec 规划文件。
+> **入口**：`/specline-pipeline <需求>` 或由编排者通过 Task 工具派发
+> **产出**：proposal.md / design.md / tasks.md / spec.md
+> **耗时**：约 30 秒 - 2 分钟
+
+**核心流程**：`需求 → 推导 change-name → 创建目录 → 生成 4 Artifact → 自检`
+
+**最终生成的文件结构**：
+
+```
+specline/changes/<change-name>/
+├── proposal.md          ← What & Why & Scope
+├── design.md            ← Architecture & Decisions
+├── tasks.md             ← 实现清单（含依赖 DAG）
+└── specs/
+    └── <capability>/
+        └── spec.md      ← Requirements & Scenarios
+```
+
+---
+
+## Layer 2: Happy Path
+
+**Input**: 用户需求描述（自然语言），由编排者传入 change-name。
+
+### Step 1: 理解需求并推导 change name
+
+如果编排者没有传入明确的 change name，从需求描述推导 kebab-case 名称（如 "添加用户登录功能" → `add-user-login`）。
+
+### Step 2: 创建 Change 目录
+
+```bash
+specline gate new --change "<name>"
+```
+
+创建 `specline/changes/<name>/` 目录及必要的元数据文件。
+
+### Step 3: 按顺序生成 4 个 Artifact
+
+| 顺序 | Artifact | 路径 | 内容要点 |
+|------|----------|------|---------|
+| 1 | proposal.md | `specline/changes/<name>/proposal.md` | What/Why/Scope/Non-goals |
+| 2 | spec.md | `specline/changes/<name>/specs/<capability>/spec.md` | Purpose/Requirements/Scenarios（WHEN/THEN） |
+| 3 | design.md | `specline/changes/<name>/design.md` | Architecture/Decisions/DataFlow/Contract |
+| 4 | tasks.md | `specline/changes/<name>/tasks.md` | Type/Depends/Covers/Files 标注 |
+
+**每个 Artifact 的创建规则**：
+
+- **proposal.md**：描述 What（做什么）/ Why（为什么做）以及以下两段（必须显式分开）：
+
+  **## In Scope**（做什么）：明确功能范围、涉及的系统/模块、目标用户
+  
+  **## Out of Scope**（不做什么）：明确排除哪些功能/场景以及排除理由。**这是提案中最有价值的部分之一**——一半的返工源于对"不做什么"的沉默分歧。明确 Out of Scope 防止需求蔓延，也保护了 In Scope 的交付承诺。
+
+  还包括：Impact（影响哪些系统）
+
+- **spec.md**：H1 标题含 "Specification"，包含 `## Purpose` 和 `## Requirements`，每个 Requirement 至少 1 个 Scenario，每个 Scenario 含 `**WHEN**`/`**THEN**` 配对，至少覆盖 Happy Path 和 1 个异常场景
+
+- **design.md**：包含 Architecture Overview、Key Design Decisions（每项说明选择理由和替代方案）、Data Flow、Component Interaction、**Architecture Impact Analysis**（侵入点/模块边界/依赖方向/数据影响/接口兼容性分析，每项标注置信度 ✅/⚠️）、**对外接口契约**（如有 specline-test-writer 负责的集成/E2E 测试；CLI 命令/HTTP 端点/模块导出签名）
+
+- **tasks.md**：每个任务必须标注：
+  - **Type**: frontend | backend | infra | db | config | docs
+  - **Depends**: (none) | 依赖的任务编号
+  - **Covers**: Requirement: xxx, Scenario: xxx
+  - **Testable**: true | false
+  - **Files**: 任务涉及的文件路径列表
+
+  任务拆分原则：
+  - 按功能领域垂直拆分（前/后端分开）
+  - `Depends: (none)` 占比 ≥ 60%
+  - 第 1 批次（无依赖任务）的 Files 集合互不重叠
+
+  > 💡 **并行度自检**：统计 tasks.md 中 `Depends: (none)` 的任务占比 — ≥ 60% 通过，< 60% 则重新拆解（最多 2 次），仍不达标则记录警告。
+
+### Step 4: 验证完整性
+
+```bash
+specline gate artifacts --change "<name>" --json
+```
+
+确保 proposal/design/tasks/specs 四个文件都已存在。
+
+### Step 5: 输出完成摘要
+
+- Change 名称和位置
+- 4 个文件生成确认
+- 任务统计（总数 N、独立任务 M、并行度 M/N）
+
+---
+
+## Layer 3: 规范详解
+
+### tasks.md 拆分规范
+
+✅ **好的任务拆分**：
+
+```markdown
+## 1. 数据模型 [x]
+- Type: backend
+- Depends: (none)
+- Covers: Requirement: 用户数据模型
+- Testable: true
+- Files: server/models/user.py
+```
+
+> 任务粒度适中，Files 范围明确，Covers 可追溯到具体 Requirement。
+
+❌ **不好的任务拆分**：
+
+```markdown
+## 1. 实现后端 [ ]
+- Type: backend
+- Files: server/*.py
+```
+
+> 太粗：Files 范围太大，没有 Covers 追溯链，Depends 缺失导致无法判断批次。
+
+---
+
+### 关键原则速查
+
+| 原则 | 说明 |
+|------|------|
+| 垂直拆分 | 按功能领域分（前/后端分开），不按技术层分 |
+| 独立可测 | 每个任务可独立验证完成状态 |
+| 文件不交叠 | 第 1 批次（Depends: none）任务的文件集合无交集 |
+| 可追溯 | 每个任务必须通过 Covers 追溯到具体 Requirement/Scenario |
+| Testable 标注 | 无依赖 + 有可测代码 + 非 config/docs → Testable: true |
+
+### 测试文件归属
+
+specline-spec-creator 生成的 tasks.md 末尾会包含「测试文件归属」表格节，按 capability 分组列出：
+
+| 测试文件（目录） | 测试类型 | 负责者 |
+|-----------------|---------|-------|
+| tests/unit/<module>/ | 单元测试 | Coding Agent (Task N) |
+| tests/integration/test_<capability>.py | 集成测试 | specline-test-writer |
+| tests/e2e/test_<capability>_flow.py | E2E 测试 | specline-test-writer |
+
+> - 单元测试（`tests/unit/` 或 `tests/models/`）归属 coding agent
+> - 集成测试（`tests/integration/`）和 E2E 测试（`tests/e2e/`）归属 specline-test-writer
+> - coding agent 和 test-writer 应只在自己的边界内编写测试文件
+
+---
+
+### Guardrails
+
+- 所有文件直接写入 `specline/changes/<name>/`，不调用外部 CLI
+- 先读已有 dependency 再生成后续文件
+- 需求不明确时用结构化提问（{{CONFIRM}}）澄清
+- 优先做出合理判断保持节奏，只在关键不清时询问
+- **Hook 阻断不降级**：如果本 Skill 因 `specline-spec-creator` 子 Agent 被 hook 阻止而作为降级方案被调用，必须首先通知用户阻断原因，并尝试诊断修复（参考 specline-pipeline SKILL 中的 Hook 阻断处理规范）。不得在 hook 问题未解决时静默直接执行
+
+---
+
+## Anti-Rationalization 表格
+
+生成 Spec 规划文件时，Agent 容易找借口跳过关键步骤：
+
+| 借口 | 现实 |
+|------|------|
+| "需求很明确，不需要 proposal.md" | 明确的只是你脑子里的假设。Proposal 的作用是让这些假设显式化，供他人审视。 |
+| "Scope 就是隐含的，不用写那么细" | 一半的返工源于对"不做什么"的沉默分歧。Out of Scope 是提案中最有价值的部分。 |
+| "任务拆解是多余的，我能直接做" | 不拆解就无法并行、无法断点续跑、无法追溯。10 分钟的拆解省下 2 小时的重做。 |
+| "并行度 50% 够了，不用追求 60%" | 60% 不是硬指标，但 <50% 意味着功能边界划分不合理——大概率任务之间耦合太紧。 |
+| "测试文件归属表格我后面补" | 补的从来不会补。没有归属表格，coding agent 和 test-writer 会踩到对方的文件。 |
+
+## Verification Checklist
+
+生成 Spec 规划文件后，自查：
+
+- [ ] proposal.md 包含：What / Why / In Scope / Out of Scope（两段显式分开）/ Impact
+- [ ] spec.md 包含：Purpose + Requirements，每个 Requirement ≥1 Scenario（含 WHEN/THEN），Happy Path + 至少 1 个异常场景
+- [ ] design.md 包含：Architecture Overview、Key Design Decisions（理由+替代方案）、Data Flow、Component Interaction、**Architecture Impact Analysis**（侵入点/模块边界/依赖方向/数据影响/接口兼容性，每项带置信度 ✅/⚠️）、**对外接口契约**（如有 test-writer 测试任务；CLI/HTTP/模块导出表格）
+- [ ] tasks.md 每个任务标注完整（Type/Depends/Covers/Testable/Files），Depends: (none) 占比 ≥ 60%，第 1 批次 Files 无重叠
+- [ ] 测试文件归属表格存在：单元测试归属 coding agent，集成/E2E 归属 test-writer
+- [ ] `specline gate artifacts --json` 确认 4 个文件齐全

package/core/skills/specline-quickfix/SKILL.md

@@ -0,0 +1,289 @@
+---
+name: specline-quickfix
+description: 轻量修改 Skill —— 小改动用 quickfix，大功能用 pipeline
+---
+
+# /specline-quickfix 轻量修改 Skill
+
+---
+
+## Layer 1: 速览与定位
+
+**一句话定位**：小改动用 quickfix，大功能用 pipeline。
+
+**入口**：`/specline-quickfix <描述>`
+
+**你做：**
+- 读取相关代码理解上下文
+<!-- platform:cursor -->
+- 直接 Write/StrReplace 编辑文件（不使用子 Agent）
+- ReadLints 自动校验 + 修复（最多 2 次循环）
+<!-- /platform:cursor -->
+<!-- platform:claude,codex,opencode -->
+- 直接编辑文件（使用平台原生编辑工具，不使用子 Agent）
+- 运行项目 linter 命令自动校验 + 修复（最多 2 次循环）
+<!-- /platform:claude,codex,opencode -->
+- 运行项目已有单元测试（失败修复最多 2 次循环）
+- 生成轻量归档（summary.md + files-changed.json）
+
+**你不做：**
+- 创建 proposal.md、design.md、tasks.md、specs/ 等规划文档
+- 启动任何 specline-* 子 Agent
+- 创建 `.pipeline-state.json` 或 `.pipeline-sessions.json`
+- 写新测试、跑集成/E2E 测试
+
+### 流程概览
+
+```
+    UNDERSTAND ──→ IMPLEMENT ──→ REVIEW ──→ TEST ──→ ARCHIVE
+     (读代码)       (直编辑)    (Lint+自审)  (现有单测)  (轻量归档)
+```
+
+### Hook 透明
+
+Quickfix 不绑定 Pipeline session，所有 Hook（sessionStart、preToolUse、postToolUse、subagentStart、beforeShellExecution）自动透明放行，不产生任何拦截或提醒。
+
+---
+
+## Layer 2: Happy Path
+
+### Phase 1: UNDERSTAND
+
+**目标**：理解变更上下文，明确修改范围。
+
+**Steps**：
+
+1. 解析用户描述，提取关键词（文件名、函数名、错误信息等）
+<!-- platform:cursor -->
+2. 使用 Read 工具读取相关源文件，理解当前逻辑
+<!-- /platform:cursor -->
+<!-- platform:claude,codex,opencode -->
+2. 读取相关源文件（使用平台原生读取工具），理解当前逻辑
+<!-- /platform:claude,codex,opencode -->
+3. 确认变更范围：
+   - 1-3 个文件 ✓
+   - 单一关注点 ✓
+   - 不涉及架构变更 ✓
+   - 不需要新测试 ✓
+4. **意图模糊时**：使用 {{CONFIRM}} 向用户确认变更范围和目标，不要猜测
+
+**准入条件**：变更范围已验证在 quickfix 适用范围内（参见 Layer 3 边界判断）
+
+---
+
+### Phase 2: IMPLEMENT
+
+**目标**：直接编辑源文件，完成修改。
+
+**Steps**：
+
+<!-- platform:cursor -->
+1. 使用 Write / StrReplace 工具直接编辑文件
+2. **不使用子 Agent**，不调用 Task 工具
+3. 编辑完成后，运行 ReadLints 检查新增的 lint 错误
+<!-- /platform:cursor -->
+<!-- platform:claude,codex,opencode -->
+1. 使用平台原生编辑工具直接编辑文件
+2. **不使用子 Agent**，不派发子任务
+3. 编辑完成后，运行项目 linter 命令检查新增的语法和风格错误
+<!-- /platform:claude,codex,opencode -->
+
+**约束**：
+- 只修改 UNDERSTAND 阶段确认的文件
+- 如果发现需要修改第 4 个文件 → 暂停并建议转 `/specline-pipeline`
+- 保持现有代码风格和命名约定
+
+---
+
+### Phase 3: REVIEW
+
+**目标**：通过 Lint 检查和 Agent 自审确保代码质量。
+
+**Steps**：
+
+<!-- platform:cursor -->
+1. 运行 ReadLints 收集所有 lint 问题
+2. **如有 lint 错误**：自动修复 → 再次 ReadLints → 最多循环 2 次
+<!-- /platform:cursor -->
+<!-- platform:claude,codex,opencode -->
+1. 运行项目 linter 命令收集所有 lint 问题
+2. **如有 lint 错误**：自动修复 → 再次运行 linter → 最多循环 2 次
+<!-- /platform:claude,codex,opencode -->
+   - 第 1 次修复后仍有错误 → 分析原因，再次修复
+   - 第 2 次修复后仍有错误 → 报告用户，附错误列表和修复尝试记录，暂停
+3. **Agent 自审**：
+   - 变更逻辑是否正确？
+   - 是否处理了边界条件？
+   - 是否引入了新问题（如未使用的导入、副作用）？
+   - 是否破坏现有功能？
+4. 自审通过 → 进入 TEST 阶段
+
+---
+
+### Phase 4: TEST
+
+**目标**：运行项目已有单元测试，确保不引入回归。
+
+**Steps**：
+
+1. **自动检测测试框架**：
+   - 检查 `package.json` scripts → Jest / Mocha / Vitest
+   - 检查 `pytest` / `go test` / `cargo test` 配置
+2. **有测试配置**：运行现有单元测试
+   - 通过 → 进入 ARCHIVE 阶段
+   - 失败 → 分析失败原因，修复代码 → 重新运行 → 最多循环 2 次
+   - 第 2 次修复后仍失败 → 报告用户（附失败详情和修复尝试记录），暂停
+3. **无测试配置**：跳过 TEST 阶段，进入 ARCHIVE 阶段（在 summary.md 中标注）
+
+**不运行**：集成测试、E2E 测试、新编写的测试。
+
+---
+
+### Phase 5: ARCHIVE
+
+**目标**：生成轻量归档，提供变更可追溯性。
+
+**Steps**：
+
+1. 在 `specline/changes/archive/` 下创建归档目录：
+   ```
+   specline/changes/archive/YYYY-MM-DD-<description>/
+       ├── summary.md
+       └── files-changed.json
+   ```
+2. **summary.md** 内容：
+   ```markdown
+   # <变更标题>
+   
+   ## What
+   <一句话描述做了什么>
+   
+   ## Why
+   <为什么要做这个修改>
+   
+   ## Files Changed
+   - path/to/file1 — <修改简述>
+   - path/to/file2 — <修改简述>
+   
+   ## Test Result
+   - 通过 / 跳过（无现有单元测试）/ 失败（附详情）
+   ```
+3. **files-changed.json** 内容：
+   ```json
+   {
+     "files": ["path/to/file1", "path/to/file2"],
+     "change_count": 2,
+     "description": "<变更描述>"
+   }
+   ```
+4. 展示变更摘要，**询问用户**：是否需要 git commit？
+
+**无人确认点**：整个 quickfix 流程不暂停等待人工确认（lint + test 是自动质量底线）。
+
+---
+
+## Layer 3: 异常与边界
+
+### Quickfix vs Pipeline 边界判断
+
+使用以下规则判断变更是否适合 quickfix：
+
+| 维度 | Quickfix (`/specline-quickfix`) | Pipeline (`/specline-pipeline`) |
+|------|-------------------------------|-------------------------------|
+| 文件改动数 | 1-3 个 | 4+ 个 |
+| 关注点 | 单一关注点 | 多关注点/跨模块 |
+| 架构变更 | 无新架构/新组件 | 需要新组件/新 API |
+| 测试 | 不需要新测试 | 需要写新测试 |
+| 典型场景 | 修 bug、改配置、文档微调 | 新增功能、重构 |
+| 产出 | summary.md + files-changed.json | proposal/design/tasks/specs + 全部测试 |
+| 人工确认 | 0 个 | 3 个 |
+| 耗时 | 1-3 分钟 | 10-30 分钟 |
+
+**边界处理规则**：
+
+| 异常情况 | 处理方式 |
+|----------|----------|
+| 变更范围 > 3 个文件 | 暂停，建议转 `/specline-pipeline` |
+| 需要写新测试 | 暂停，建议转 `/specline-pipeline` |
+| 涉及架构变更/新 API | 暂停，建议转 `/specline-pipeline` |
+| Lint 修复 2 次后仍有错误 | 报告用户（附错误列表和修复记录），暂停 |
+| 测试失败 2 次后仍失败 | 报告用户（附失败详情和修复记录），暂停 |
+| 实现过程中发现需要额外文件 | 如果总数仍 ≤ 3 → 继续；如果 > 3 → 暂停并建议转 pipeline |
+| 项目无测试配置 | 跳过 TEST 阶段，在 summary.md 中标注 |
+
+### 不适合 Quickfix 的典型场景
+
+- 新增功能模块（需要 spec/design 规划）
+- 跨 3+ 模块的接口变更
+- 数据库 schema 变更
+- 需要新增测试覆盖的复杂修复
+- 需要多人/多步骤协调的改动
+
+**使用建议**：如果不确定，优先用 quickfix。如果需要更严格的流程保证，用 pipeline。
+
+---
+
+## Layer 4: 附录
+
+### 与 Pipeline 的关系
+
+```
+specline-pipeline (完整流程)           specline-quickfix (轻量流程)
+    SPEC                                  UNDERSTAND
+     ↓                                       ↓
+    CODING (子 Agent 并发)                   IMPLEMENT (单 Agent 直编)
+     ↓                                       ↓
+    CODE REVIEW (review Agent)              REVIEW (Lint 检查 + 自审)
+     ↓                                       ↓
+    TEST (unit → integration → e2e)         TEST (现有单测 only)
+     ↓                                       ↓
+    ARCHIVE (Delta sync)                    ARCHIVE (summary + files-changed)
+```
+
+两者完全独立，通过边界判断规则选择。不共享状态文件，不互相依赖。
+
+### 归档目录结构兼容性
+
+Quickfix 归档目录结构与 Pipeline 归档保持一致：
+
+```
+specline/changes/archive/
+├── YYYY-MM-DD-<pipeline-change>/       ← Pipeline 归档
+│   ├── proposal.md
+│   ├── design.md
+│   ├── tasks.md
+│   ├── specs/
+│   └── ...
+│
+└── YYYY-MM-DD-<quickfix-description>/   ← Quickfix 归档
+    ├── summary.md
+    └── files-changed.json
+```
+
+两种归档方式共存于同一目录，通过内容区分（Pipeline 归档有 proposal.md 等完整文档，Quickfix 归档只有 summary.md + files-changed.json）。
+
+---
+
+## Anti-Rationalization 表格
+
+Quickfix 的极简流程容易让人产生"反正很快，随便点"的心态：
+
+| 借口 | 现实 |
+|------|------|
+| "顺便多改一个文件也没事，就一行" | Quickfix 的 1-3 文件边界是防止范围蔓延的最后防线。第 4 个文件应该走 Pipeline。 |
+| "不需要 lint 检查，我肉眼确认了" | 人类肉眼无法可靠检测拼写错误、未使用导入、类型不匹配。Lint 检查是自动化底线。 |
+| "测试跳过没事，改动很小" | 改动越小越容易有隐性耦合。现有测试套件就是你的回归检测网。 |
+| "不用归档了，就是个小修，没记录无所谓" | 不归档意味着不可追溯。三个月后没人记得这个修改是谁做的、为什么做的。 |
+| "不用询问用户 git commit，我自己提交了" | Commit 是用户的决定，不是 Agent 的。擅自 commit 剥夺了用户的审查机会。 |
+
+## Verification Checklist
+
+Quickfix 完成后，自查：
+
+- [ ] UNDERSTAND 阶段确认了变更范围（≤3 文件，单一关注点）
+- [ ] IMPLEMENT 阶段只修改了确认的文件，未越界
+- [ ] REVIEW 阶段 lint 检查通过（或 2 次修复后仍有错误已报告）
+- [ ] Agent 自审完成：逻辑正确、边界已处理、未引入新问题、未破坏现有功能
+- [ ] TEST 阶段现有单元测试全部通过（或已标注跳过原因）
+- [ ] ARCHIVE 阶段 summary.md + files-changed.json 已写入归档目录
+- [ ] 已询问用户是否需要 git commit

package/core/templates/AGENTS.md.hbs

@@ -0,0 +1,5 @@
+# Specline bootstrap
+
+> 本段由 specline init 自动生成，请勿手动编辑 bootstrap 部分。
+
+{{bootstrap}}

package/core/templates/specline/config.yaml

@@ -0,0 +1,15 @@
+# Specline 项目配置
+# 此文件由 specline init 生成，可按需修改
+
+pipeline:
+  # 人机门禁策略: full / minimal / none
+  # full    — HG1(SPEC确认) + HG2(Review复核) + HG3(归档确认) 均人工
+  # minimal — HG1 人工确认，HG2/HG3 自动通过
+  # none    — 全部自动通过
+  human_gate_policy: full
+
+gate:
+  # Gate 脚本调用方式
+  command: specline gate
+  # CLI 不可用时回退到本地脚本
+  fallback: specline/bin/gate.sh

package/lib/deploy-claude.mjs

@@ -0,0 +1,80 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { PACKAGE_ROOT } from './paths.mjs';
+import { getClaudeUpstreamManifest, writeManifestToProject } from './deploy.mjs';
+import { mergeClaudeSettings, backupBeforeOverwrite } from './merge.mjs';
+
+/**
+ * Deploy Specline assets to a Claude Code project.
+ *
+ * Skills  -> .claude/skills/  |  Agents -> .claude/agents/*.md
+ * Hook   -> merge .claude/settings.json (SessionStart)
+ *
+ * @param {string} projectDir  Target project root
+ * @param {{ packageRoot?: string, dryRun?: boolean }} [options]
+ * @returns {{ filesWritten: string[], settingsAction: 'created'|'merged'|'unchanged' }}
+ */
+export function deployClaude(projectDir, options = {}) {
+  const { packageRoot = PACKAGE_ROOT, dryRun = false } = options;
+
+  const manifest = getClaudeUpstreamManifest(packageRoot);
+
+  const settingsRel = '.claude/settings.json';
+  manifest.delete(settingsRel);
+
+  const filesWritten = [];
+
+  if (!dryRun) {
+    for (const dir of ['.claude/skills', '.claude/agents']) {
+      const full = join(projectDir, dir);
+      if (!existsSync(full)) mkdirSync(full, { recursive: true });
+    }
+    writeManifestToProject(projectDir, manifest);
+  }
+  for (const rel of manifest.keys()) filesWritten.push(rel);
+
+  const settingsAction = mergeClaudeSettingsFile(projectDir, packageRoot, dryRun);
+
+  filesWritten.push(settingsRel);
+  return { filesWritten, settingsAction };
+}
+
+/**
+ * Merge .claude/settings.json with Specline hooks template.
+ *
+ * - Existing file: backup → merge hooks.SessionStart → preserve user config
+ * - No file: create with hooks section only
+ *
+ * @param {string} projectDir
+ * @param {string} packageRoot
+ * @param {boolean} dryRun
+ * @returns {'created'|'merged'|'unchanged'}
+ */
+function mergeClaudeSettingsFile(projectDir, packageRoot, dryRun) {
+  const settingsPath = join(projectDir, '.claude', 'settings.json');
+  const templatePath = join(packageRoot, 'adapters', 'claude', 'hooks', 'hooks.json');
+  if (!existsSync(templatePath)) return 'unchanged';
+
+  const templateContent = readFileSync(templatePath, 'utf-8');
+
+  if (existsSync(settingsPath)) {
+    const existingContent = readFileSync(settingsPath, 'utf-8');
+    const merged = mergeClaudeSettings(existingContent, templateContent);
+    if (merged === existingContent) return 'unchanged';
+
+    if (!dryRun) {
+      backupBeforeOverwrite(settingsPath);
+      writeFileSync(settingsPath, merged, 'utf-8');
+    }
+    return 'merged';
+  }
+
+  if (!dryRun) {
+    const dir = dirname(settingsPath);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+    const freshSettings = mergeClaudeSettings('', templateContent);
+    writeFileSync(settingsPath, freshSettings, 'utf-8');
+  }
+  return 'created';
+}

package/lib/deploy-codex.mjs

@@ -0,0 +1,77 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { PACKAGE_ROOT } from './paths.mjs';
+import { getCodexUpstreamManifest, writeManifestToProject } from './deploy.mjs';
+import { mergeHooksJson } from './merge.mjs';
+
+/**
+ * Deploy Specline assets to a Codex project.
+ *
+ * Skills -> .codex/skills/  |  Agents -> .codex/agents/*.toml (YAML -> TOML)
+ * Hook  -> .codex/hooks.json (copy or merge)
+ *
+ * @param {string} projectDir  Target project root
+ * @param {{ packageRoot?: string, dryRun?: boolean }} [options]
+ * @returns {{ filesWritten: string[], hooksAction: 'created'|'merged'|'unchanged' }}
+ */
+export function deployCodex(projectDir, options = {}) {
+  const { packageRoot = PACKAGE_ROOT, dryRun = false } = options;
+
+  const manifest = getCodexUpstreamManifest(packageRoot);
+
+  const hooksRel = '.codex/hooks.json';
+  manifest.delete(hooksRel);
+
+  const filesWritten = [];
+
+  if (!dryRun) {
+    for (const dir of ['.codex/skills', '.codex/agents']) {
+      const full = join(projectDir, dir);
+      if (!existsSync(full)) mkdirSync(full, { recursive: true });
+    }
+    writeManifestToProject(projectDir, manifest);
+  }
+  for (const rel of manifest.keys()) filesWritten.push(rel);
+
+  const hooksAction = mergeCodexHooksFile(projectDir, packageRoot, dryRun);
+
+  filesWritten.push(hooksRel);
+  return { filesWritten, hooksAction };
+}
+
+/**
+ * Merge .codex/hooks.json with Specline hooks template.
+ *
+ * - Existing file: merge (preserve user-defined hooks, update specline hooks)
+ * - No file: copy from adapters/codex/hooks.json
+ *
+ * @param {string} projectDir
+ * @param {string} packageRoot
+ * @param {boolean} dryRun
+ * @returns {'created'|'merged'|'unchanged'}
+ */
+function mergeCodexHooksFile(projectDir, packageRoot, dryRun) {
+  const hooksPath = join(projectDir, '.codex', 'hooks.json');
+  const templatePath = join(packageRoot, 'adapters', 'codex', 'hooks.json');
+  if (!existsSync(templatePath)) return 'unchanged';
+
+  const templateContent = readFileSync(templatePath, 'utf-8');
+
+  if (existsSync(hooksPath)) {
+    const existingContent = readFileSync(hooksPath, 'utf-8');
+    const merged = mergeHooksJson(existingContent, templateContent);
+    if (merged === existingContent) return 'unchanged';
+
+    if (!dryRun) {
+      writeFileSync(hooksPath, merged, 'utf-8');
+    }
+    return 'merged';
+  }
+
+  if (!dryRun) {
+    const dir = dirname(hooksPath);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    copyFileSync(templatePath, hooksPath);
+  }
+  return 'created';
+}