Merge pull request #1 from arch-team/feature/v1.5.0-external-sync

feat: v1.5.0 外部同步 + pace-init 架构优化

Author: arch-team

.claude-plugin/marketplace.json

@@ -8,11 +8,11 @@
     {
       "name": "devpace",
       "description": "Development pace manager — value-driven iterative workflow connecting business goals to code changes",
-      "version": "1.4.1",
+      "version": "1.5.0",
       "source": {
         "source": "github",
         "repo": "arch-team/devpace",
-        "ref": "v1.4.1"
+        "ref": "v1.5.0"
       },
       "author": {
         "name": "paceforge"

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "devpace",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "AI-native development pace manager for Claude Code — change impact analysis, quality gates, goal-to-code traceability, and cross-session continuity",
   "author": {
     "name": "paceforge"

.claude/CLAUDE.md

@@ -29,6 +29,7 @@ devpace 分为两个独立层次，**产品层不得依赖开发层**：
 2. **禁止产品→开发引用**：产品层文件（rules/、skills/、knowledge/）中不得出现指向 `docs/` 或 `.claude/` 的路径引用
 3. **开发→产品引用允许**：开发层文件（.claude/CLAUDE.md、docs/design.md 等）可以引用产品层文件
 4. **共享知识归产品层**：如果一份内容同时被开发和产品使用（如 theory.md），它必须放在产品层（knowledge/），开发层引用它
+5. **编辑范围严格分层**：修改产品层文件（`rules/`、`skills/`、`knowledge/`）时，不得将开发层文件（`docs/`、`.claude/`）纳入同一批次的编辑范围；反之亦然。跨层引用（如 `docs/features/` 引用 `skills/` 中的章节编号）在产品层变更后可能过时，但应在独立的开发层维护任务中处理，不可混入产品层变更
 
 **检查方法**：`grep -r "docs/\|\.claude/" rules/ skills/ knowledge/` 应返回空结果。
 
@@ -87,3 +88,4 @@ devpace 分为两个独立层次，**产品层不得依赖开发层**：
   - accept 能力描述：`skills/pace-test/SKILL.md`（权威）→ `rules/devpace-rules.md §15`（教学派生）→ `docs/user-guide.md`（文档派生）
   - 子命令列表：各 `SKILL.md`（权威）→ `devpace-rules.md §0`（目录索引）→ `user-guide.md`（文档派生）→ `test-procedures.md 职责行`（测试派生）
   - 推荐使用流程：`SKILL.md`（权威）→ `user-guide.md`（文档派生）
+  - 特性文档同步：各 `SKILL.md`（权威）→ `docs/features/<skill-name>.md`（文档派生）→ `docs/features/<skill-name>_zh.md`（翻译派生）

.claude/rules/dev-workflow.md

@@ -126,6 +126,7 @@ graph LR
   - Schema 修改：现有模板文件仍符合修改后的 Schema
   - 模板更新：用 Schema 字段逐一对照模板占位符完整性
   - 通用：对照 requirements.md 相关 S/F 条目的验收标准逐条检查
+- [ ] 特性文档同步：修改 Skill 子命令/行为时，检查 `docs/features/` 对应文档是否需要更新
 
 ### Skill 内容质量验证方法（推荐）
 

CHANGELOG.md

@@ -8,6 +8,7 @@ All notable changes to devpace are documented here. For English release summarie
 
 | Version | Date | Highlights |
 |---------|------|-----------|
+| [1.5.0](#150---2026-02-25) | 2026-02-25 | External Tool Sync — semantic bridge to GitHub Issues (push-only MVP) |
 | [1.4.0](#140---2026-02-25) | 2026-02-25 | Risk Fabric — pre-flight risk scan + runtime monitoring + graduated response |
 | [1.3.0](#130---2026-02-24) | 2026-02-24 | DORA proxy metrics + cross-project insights + CI/CD auto-detection |
 | [1.2.0](#120---2026-02-24) | 2026-02-24 | Test management (/pace-test) + global navigation (/pace-next) |
@@ -25,6 +26,36 @@ All notable changes to devpace are documented here. For English release summarie
 
 ## [Unreleased]
 
+## [1.5.0] - 2026-02-25
+
+外部工具语义桥接——将 devpace 研发状态与 GitHub Issues 形成语义级同步，Claude 理解变更意图后生成对应外部操作，而非机械的字段映射。v1.5.0 为 push-only MVP。
+
+### Added
+
+**外部工具同步（/pace-sync）**
+
+- **4 子命令 MVP 同步体系**：`setup`（引导式配置：检测 git remote → 生成 sync-mapping.md）、`link`（关联 CR ↔ GitHub Issue）、`push`（推送状态：标签更新 + 评论记录）、`status`（同步状态和一致性检查）
+- **sync-mapping-format.md Schema**：同步配置格式契约（平台配置 + CR 状态映射 + 实体映射 + Gate 结果同步 + 关联记录）
+- **sync-push.mjs advisory hook**：PostToolUse hook，CR 状态变更后非阻断提醒推送（始终 exit 0）
+- **devpace-rules.md §16 同步管理**：条件生效规则——sync-mapping.md 存在时激活，定义同步行为和教学提示
+- **适配器工具路由表**：GitHub（gh CLI）为 MVP 默认，Linear（MCP）和 Jira 预留 Phase 19+
+
+### Changed
+
+- **conftest.py**：SKILL_NAMES 列表新增 `pace-sync`，SCHEMA_FILES 新增 `sync-mapping-format.md`
+- **plugin.json**：新增 pace-sync Skill 声明和 sync-push hook 配置
+- **devpace-rules.md §0**：速查卡片追加同步相关内容 + 命令分层进阶行追加 /pace-sync
+- **cr-format.md**：新增"外部关联"可选字段
+- **version bump**：conftest.py 版本号 → 1.5.0
+
+### Backward Compatible
+
+- /pace-sync 为全新 Skill，不影响已有命令和工作流
+- sync-mapping.md 为可选配置——不存在时核心流程完全不受影响
+- sync-push hook 为 advisory（仅提醒，不阻断），不改变现有 hook 行为
+- CR Schema 的"外部关联"字段为可选——已有 CR 不受影响
+- 所有降级行为静默处理，不中断用户工作流
+
 ## [1.4.0] - 2026-02-25
 
 Risk Fabric 风险织网——Pre-flight 风险扫描 + Runtime 风险监控 + 趋势分析 + 分级自主响应，将风险管理编织进开发全流程。

CONTRIBUTING.md

@@ -104,7 +104,7 @@ graph TB
             Hooks["hooks/ (lifecycle interceptors)"]
         end
         subgraph "On-demand layer"
-            Skills["skills/ (14 user commands + 2 system Skills)"]
+            Skills["skills/ (16 user commands + 2 system Skills)"]
             Agents["agents/ (sub-task executors)"]
         end
         subgraph "Knowledge layer"

CONTRIBUTING_zh.md

@@ -104,7 +104,7 @@ graph TB
             Hooks["hooks/ (生命周期拦截)"]
         end
         subgraph "按需触发层"
-            Skills["skills/ (14 个用户命令 + 2 个系统 Skill)"]
+            Skills["skills/ (16 个用户命令 + 2 个系统 Skill)"]
             Agents["agents/ (子任务执行者)"]
         end
         subgraph "知识层"

README.md

@@ -31,15 +31,30 @@ When using Claude Code for product development:
 
 Next session, Claude reports: "Last time we stopped at auth module, continue?" — zero manual re-explanation.
 
+## Full Development Lifecycle
+
+```
+ Goal         Features       Code Changes      Quality         Ship
+You define ──→ Plan together ──→ Claude codes ──→ Auto + You ──→ Optional auto
+                │                   │               │              │
+             pace-plan          pace-dev        pace-review    pace-release
+             pace-change                                       pace-feedback
+```
+
+Requirements can change anytime — `/pace-change` auto-analyzes impact, adjusts the plan, and waits for your confirmation.
+
+After each cycle, `/pace-retro` shows quality metrics and improvement trends.
+
 ## How It Works
 
-devpace is a Claude Code Plugin that extends Claude's capabilities through three mechanisms:
+devpace builds a **goal-to-code traceability chain** in your project:
 
-- **Rules**: Define Claude's behavioral guidelines — when to auto-check quality, how to trace goals
-- **Skills**: `/pace-*` command series, triggering specific workflows
-- **Hooks**: Auto-trigger at critical moments — check quality before writing code, restore context on session start
+1. **Goal alignment** — Every code change links back to a business goal. No work without purpose.
+2. **Auto quality gates** — Claude auto-checks code quality and requirement consistency, self-repairs on failure. Human approval cannot be skipped.
+3. **Change is normal** — Requirements changed? Auto impact analysis, orderly adjustment, existing work preserved.
+4. **Interrupt-proof** — Session broke? Auto-resume next time. All state in `.devpace/` as plain Markdown.
 
-All state is stored in `.devpace/` folder at project root, pure Markdown, human-readable.
+Under the hood: a Claude Code Plugin using Rules (behavioral guidelines) + Skills (`/pace-*` commands) + Hooks (auto-triggers at critical moments).
 
 ## Installation
 
@@ -93,6 +108,7 @@ After installing, type `/pace-` in Claude Code. If devpace is loaded, you'll see
 | `/pace-test` | Requirements-traceable test management |
 | `/pace-guard` | Risk fabric: Pre-flight scan + Runtime monitoring + Trend analysis + Graduated response |
 | `/pace-release` | Release orchestration: Changelog + Version bump + Git Tag + GitHub Release |
+| `/pace-sync` | External tool bridge: sync task state ↔ GitHub Issues (labels + comments) |
 | `/pace-role` | Switch perspective (PM / Tester / Ops / etc.) |
 | `/pace-theory` | Learn the methodology behind devpace |
 | `/pace-feedback` | Collect post-launch feedback |
@@ -141,12 +157,18 @@ When unsure, Claude asks: "Ready to start coding, or just exploring?"
 ### Workflow
 
 ```
+Normal flow:
 Start ──→ In Progress ──→ Pending Review ──→ Done
               │                │
-        Auto quality check  You approve      Auto merge
-        (Claude handles)   (you decide)    + status update
+        Auto quality check  You approve      Auto merge + status update
+        (Claude handles)   (you decide)
+
+Anytime:
+  Requirements changed ──→ Impact analysis ──→ Adjust plan ──→ Continue
+  Session interrupted  ──→ Next session auto-resumes from where you left off
 
-Pause anytime, resume from where you left off
+Full cycle (optional):
+  Plan (pace-plan) → Build (pace-dev) → Review (pace-retro) → Next cycle
 ```
 
 ## Design Principles
@@ -158,6 +180,16 @@ Pause anytime, resume from where you left off
 | Byproducts not prerequisites | Structured data is auto-produced from work, not a required input |
 | Interruption tolerance | Interrupt at any point, seamless resume next time |
 
+## vs Alternatives
+
+| Dimension | GitHub Issues / Manual | devpace |
+|-----------|----------------------|---------|
+| Core model | Task list | Goal → Feature → Code Change traceability |
+| Requirement changes | Manual impact assessment | Auto impact analysis + orderly adjustment |
+| Claude's role | Executor (you direct each step) | Autonomous collaborator (auto-advances, self-checks, waits for your decisions) |
+| Traceability | Task → Code | Business Goal → Feature → Change → Code |
+| Metrics | Completion count | Quality pass rate + value alignment + DORA proxies |
+
 ## What devpace is NOT
 
 - **Not a CI/CD pipeline** — it works alongside your existing tools (GitHub Actions, Jenkins, etc.)

README_zh.md

@@ -31,15 +31,30 @@
 
 下次开会话，Claude 自动报告："上次停在认证模块，继续？"——零手动解释。
 
+## 覆盖完整研发生命周期
+
+```
+  目标         功能         代码变更          质量          发布
+你来定义 ──→ 一起规划 ──→ Claude 写代码 ──→ 自动+你审批 ──→ 可选自动
+               │                │               │              │
+           pace-plan        pace-dev       pace-review    pace-release
+           pace-change                                    pace-feedback
+```
+
+需求随时可变——`/pace-change` 自动分析影响、调整计划、等你确认。
+
+每轮结束后，`/pace-retro` 展示质量指标和改进趋势。
+
 ## 工作原理
 
-devpace 是一个 Claude Code Plugin，通过三种机制扩展 Claude 的能力：
+devpace 在你的项目中构建一条**从目标到代码的追溯链**：
 
-- **Rules**（规则）：定义 Claude 的行为准则——何时自动检查质量、如何追溯目标
-- **Skills**（命令）：`/pace-*` 系列命令，触发特定工作流
-- **Hooks**（自动触发）：在关键时刻自动执行——如写代码前检查质量、会话开始时恢复上下文
+1. **目标对齐** —— 每个代码变更都关联到业务目标。没有目的的工作不会发生。
+2. **自动质量门禁** —— Claude 自动检查代码质量和需求一致性，失败自动修复。人类审批不可跳过。
+3. **变更是常态** —— 需求变了？自动影响分析，有序调整，已有工作保留。
+4. **中断无忧** —— 会话断了？下次自动恢复。所有状态在 `.devpace/` 中，纯 Markdown。
 
-所有状态存储在项目根目录的 `.devpace/` 文件夹中，纯 Markdown 格式，人类可读。
+底层机制：一个 Claude Code Plugin，通过 Rules（行为准则）+ Skills（`/pace-*` 命令）+ Hooks（关键时刻自动触发）实现。
 
 ## 安装
 
@@ -93,6 +108,7 @@ claude --plugin-dir /path/to/devpace
 | <nobr>`/pace-test`</nobr> | 需求追溯驱动的测试管理 |
 | <nobr>`/pace-guard`</nobr> | 风险织网：Pre-flight 扫描 + Runtime 监控 + 趋势分析 + 分级响应 |
 | <nobr>`/pace-release`</nobr> | 发布编排：Changelog + 版本 bump + Git Tag + GitHub Release |
+| <nobr>`/pace-sync`</nobr> | 外部工具桥接：任务状态 ↔ GitHub Issues 同步（标签 + 评论） |
 | <nobr>`/pace-role`</nobr> | 切换视角（产品经理/测试/运维等） |
 | <nobr>`/pace-theory`</nobr> | 了解背后的方法论 |
 | <nobr>`/pace-feedback`</nobr> | 收集上线后反馈 |
@@ -141,12 +157,18 @@ claude --plugin-dir /path/to/devpace
 ### 工作流程
 
 ```
+常规流程：
 开始做 ──→ 在做 ──→ 待审批 ──→ 完成
             │         │
-       质量自动检查  你来审批      自动合并
-      （Claude 处理）（你决定）    + 状态更新
+       质量自动检查  你来审批      自动合并 + 状态更新
+      （Claude 处理）（你决定）
+
+随时：
+  需求变了 ──→ 影响分析 ──→ 调整计划 ──→ 继续
+  会话中断 ──→ 下次自动从断点恢复
 
-随时可暂停，恢复时从断点继续
+完整循环（可选）：
+  规划 (pace-plan) → 开发 (pace-dev) → 回顾 (pace-retro) → 下一轮
 ```
 
 ## 设计原则
@@ -158,6 +180,16 @@ claude --plugin-dir /path/to/devpace
 | <nobr>副产物非前置</nobr> | 结构化数据是工作的自动产出，不是前置要求 |
 | <nobr>中断容错</nobr> | 任意时刻中断，下次无缝恢复 |
 
+## 与替代方案的对比
+
+| 维度 | GitHub Issues / 手动管理 | devpace |
+|------|------------------------|---------|
+| 核心模型 | 任务列表 | 目标 → 功能 → 代码变更追溯链 |
+| 需求变更 | 人工评估影响 | 自动影响分析 + 有序调整 |
+| Claude 的角色 | 执行者（你指挥每一步） | 自主协作者（自动推进、自检、等你决策） |
+| 追溯性 | 任务 → 代码 | 业务目标 → 功能 → 变更 → 代码 |
+| 度量 | 完成数量 | 质量通过率 + 价值对齐 + DORA 代理值 |
+
 ## devpace 不是什么
 
 - **不是 CI/CD 流水线** —— 它与你现有的工具（GitHub Actions、Jenkins 等）并行工作