diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 3cbbd2e..0e354d6 100644 --- a/.claude-plugin/marketplace.json +++ b/.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" diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 19b57c9..5e1316a 100644 --- a/.claude-plugin/plugin.json +++ b/.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" diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 209a962..c68351c 100644 --- a/.claude/CLAUDE.md +++ b/.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/.md`（文档派生）→ `docs/features/_zh.md`（翻译派生） diff --git a/.claude/rules/dev-workflow.md b/.claude/rules/dev-workflow.md index d4d4f71..c263c19 100644 --- a/.claude/rules/dev-workflow.md +++ b/.claude/rules/dev-workflow.md @@ -126,6 +126,7 @@ graph LR - Schema 修改：现有模板文件仍符合修改后的 Schema - 模板更新：用 Schema 字段逐一对照模板占位符完整性 - 通用：对照 requirements.md 相关 S/F 条目的验收标准逐条检查 +- [ ] 特性文档同步：修改 Skill 子命令/行为时，检查 `docs/features/` 对应文档是否需要更新 ### Skill 内容质量验证方法（推荐） diff --git a/CHANGELOG.md b/CHANGELOG.md index 5a71838..c0e03c3 100644 --- a/CHANGELOG.md +++ b/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 风险监控 + 趋势分析 + 分级自主响应，将风险管理编织进开发全流程。 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4c7ac00..2fa9076 100644 --- a/CONTRIBUTING.md +++ b/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" diff --git a/CONTRIBUTING_zh.md b/CONTRIBUTING_zh.md index 49936ab..71336c8 100644 --- a/CONTRIBUTING_zh.md +++ b/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 "知识层" diff --git a/README.md b/README.md index 5f9cda9..78c716c 100644 --- a/README.md +++ b/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.) diff --git a/README_zh.md b/README_zh.md index 2ada708..18aaf73 100644 --- a/README_zh.md +++ b/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 | `/pace-test` | 需求追溯驱动的测试管理 | | `/pace-guard` | 风险织网：Pre-flight 扫描 + Runtime 监控 + 趋势分析 + 分级响应 | | `/pace-release` | 发布编排：Changelog + 版本 bump + Git Tag + GitHub Release | +| `/pace-sync` | 外部工具桥接：任务状态 ↔ GitHub Issues 同步（标签 + 评论） | | `/pace-role` | 切换视角（产品经理/测试/运维等） | | `/pace-theory` | 了解背后的方法论 | | `/pace-feedback` | 收集上线后反馈 | @@ -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 | 副产物非前置 | 结构化数据是工作的自动产出，不是前置要求 | | 中断容错 | 任意时刻中断，下次无缝恢复 | +## 与替代方案的对比 + +| 维度 | GitHub Issues / 手动管理 | devpace | +|------|------------------------|---------| +| 核心模型 | 任务列表 | 目标 → 功能 → 代码变更追溯链 | +| 需求变更 | 人工评估影响 | 自动影响分析 + 有序调整 | +| Claude 的角色 | 执行者（你指挥每一步） | 自主协作者（自动推进、自检、等你决策） | +| 追溯性 | 任务 → 代码 | 业务目标 → 功能 → 变更 → 代码 | +| 度量 | 完成数量 | 质量通过率 + 价值对齐 + DORA 代理值 | + ## devpace 不是什么 - **不是 CI/CD 流水线** —— 它与你现有的工具（GitHub Actions、Jenkins 等）并行工作 diff --git a/docs/design/design.md b/docs/design/design.md index e23acab..64de16d 100644 --- a/docs/design/design.md +++ b/docs/design/design.md @@ -1165,6 +1165,97 @@ open ──→ mitigated ──→ resolved --- +## §19 外部工具同步（可选扩展） + +### 设计目标 + +让 devpace 与外部项目管理工具（GitHub/Linear/Jira/GitLab）形成语义级双向桥接，使 BizDevOps 价值链跨工具完整。 + +### 核心创新：语义桥接 vs 字段映射 + +传统集成做"字段 A → 字段 B"的机械映射。devpace 利用 Claude 理解能力做**语义桥接**： +- CR `developing` 不是简单映射为 GitHub `in progress` 标签，而是 Claude 理解"这个变更请求正在被实现"并生成对应操作 +- 外部 PR merged 不只触发状态变化，而是 Claude 理解"代码已合入，需要推进质量门检查" +- 冲突不是"谁赢"的规则，而是 Claude 分析两侧上下文后给出智能建议 + +### 分层架构 + +``` +┌──────────────────────────────────┐ +│ pace-sync Skill 层 │ +│ setup/link/push/pull/sync/ │ +│ resolve/status │ +├──────────────────────────────────┤ +│ 操作编排（sync-procedures.md） │ +│ 平台无关的子命令步骤序列 │ +├──────────────────────────────────┤ +│ 平台适配器（sync-adapter-*.md）│ +│ 操作表 + 状态策略 + 限流规则 │ +├──────────────────────────────────┤ +│ 现有 MCP/CLI（不自建） │ +│ gh CLI / Linear MCP / Jira MCP │ +├──────────────────────────────────┤ +│ 配置层 │ +│ sync-mapping.md + config.md │ +└──────────────────────────────────┘ +``` + +**关键决策**： +- 不自建 MCP Server——GitHub/Linear/Jira/GitLab 都有成熟的现有工具，devpace 只聚焦语义编排层 +- 适配器按平台拆分为独立文件（sync-adapter-github.md 等），sync-procedures.md 使用操作语义引用适配器，新增平台零修改 procedures（OCP） + +### 适配器路由 + +| 平台 | 适配器文件 | 工具 | 状态 | +|------|-----------|------|------| +| GitHub | sync-adapter-github.md | gh CLI | 可用 | +| Linear | sync-adapter-linear.md | MCP | Phase 19 | +| Jira | sync-adapter-jira.md | MCP/CLI | Phase 19+ | + +MVP 默认 GitHub（通过 gh CLI，零依赖）。子命令使用操作语义（如"验证连接"、"更新状态标记"），Claude 按 sync-mapping.md 平台字段加载对应适配器文件执行。 + +### 事件模型 + +**出站（devpace → 外部）**： + +| 触发 | 操作 | Phase | +|------|------|:-----:| +| CR created + 有配置 | 建议创建 Issue（或自动创建） | 18/19 | +| CR 状态变更 | 更新标签 + 语义 Comment | 18 | +| Gate 结果 | 推送 Comment + 结果标签 | 19 | +| CR merged | 关闭 Issue + done 标签 + 完成摘要 | 18 | +| Release 发布 | Release Draft / Tag | 19 | + +**入站（外部 → devpace，Phase 20）**： + +| 触发 | 操作 | 实现方式 | +|------|------|---------| +| Issue 创建/更新 | 建议创建/更新 CR | 轮询 | +| PR merged | 触发 Gate 1 | 轮询 | +| CI 通过/失败 | 更新 Gate 1 | 轮询 | + +### 入站架构约束 + +**CLI Plugin 无 webhook 能力**——Claude Code Plugin 运行在用户本地 CLI 环境中，没有持续运行的 HTTP 服务器，无法接收 webhook 回调。 + +**轮询架构设计**（Phase 20）： +- **触发时机**：会话开始时（§1 扩展）+ 用户显式 `/pace-sync pull` +- **轮询范围**：仅查询已关联的外部实体（sync-mapping.md 关联记录表），不做全量扫描 +- **变更检测**：比较外部实体的 `updated_at` 与 sync-mapping.md 的"最后同步"时间戳 +- **冲突处理**：两侧同时变更 → 按 sync-mapping.md "冲突策略"决定（ask-user 为默认） + +**设计原则**：入站能力（pull）与出站能力（push）完全解耦——即使 pull 未实现，push 独立完整可用。 + +### 与治理基础设施协调 + +pace-sync 是 orchestrator 不是 executor，尊重项目已有的 Issue 模板、PR 模板、CODEOWNERS、Release 工作流。 + +### 渐进实施 + +Phase 18（语义 MVP + merged 闭环）→ Phase 19（智能推送 + Issue 生命周期）→ Phase 20（轮询入站 + 冲突解决） + +--- + ## 附录 A：对 rules 的补强建议 在设计方案重写过程中识别的 rules 空白，记录为后续任务： @@ -1183,7 +1274,7 @@ open ──→ mitigated ──→ resolved ## 附录 B：组件依赖图 -devpace 完整架构的组件依赖关系。图中展示 17 个 Skill、3 个 Agent、5 个 Hook 脚本、12 个 Schema、5 个 Knowledge 文件及其相互依赖。 +devpace 完整架构的组件依赖关系。图中展示 18 个 Skill、3 个 Agent、5 个 Hook 脚本、13 个 Schema、5 个 Knowledge 文件及其相互依赖。 ```mermaid graph TB @@ -1200,7 +1291,7 @@ graph TB RULES["devpace-rules.md
§0-§15 核心规则"]:::rules %% ============ 用户触发 Skill（蓝底）============ - subgraph UserSkills["用户触发 Skill（15）"] + subgraph UserSkills["用户触发 Skill（16）"] direction TB INIT["/pace-init"]:::userSkill DEV["/pace-dev"]:::userSkill @@ -1217,6 +1308,7 @@ graph TB ROLE["/pace-role"]:::userSkill THEORY["/pace-theory"]:::userSkill TRACE["/pace-trace"]:::userSkill + SYNC["/pace-sync"]:::userSkill end %% ============ 系统自动 Skill（绿底）============ @@ -1242,7 +1334,7 @@ graph TB end %% ============ Schema（紫底）============ - subgraph Schemas["Schema（12）"] + subgraph Schemas["Schema（13）"] direction TB S_STATE["state-format"]:::schema S_CR["cr-format"]:::schema @@ -1256,6 +1348,7 @@ graph TB S_TESTSTRATEGY["test-strategy-format"]:::schema S_TESTBASELINE["test-baseline-format"]:::schema S_RISK["risk-format"]:::schema + S_SYNCMAP["sync-mapping-format"]:::schema end %% ============ Knowledge（紫底浅色）============ @@ -1325,6 +1418,13 @@ graph TB GUARD -->|"趋势数据→回顾"| RETRO PULSE -->|"第 8 信号→monitor"| GUARD + %% ============ pace-sync 依赖网络 ============ + SYNC -.->|"读写"| S_SYNCMAP + SYNC -.->|"读取"| S_CR + SYNC -.->|"读取"| S_INTEGRATIONS + RULES -->|"§16 同步管理"| SYNC + RULES -->|"§11 第 7 步"| SYNC + %% ============ pace-test 依赖网络（重点新增）============ TEST -.->|"读取"| S_CR TEST -.->|"读取"| S_CHECKS @@ -1358,11 +1458,11 @@ graph TB | 颜色 | 含义 | 数量 | |------|------|:----:| | 🔴 红底 | Rules 中心枢纽 | 1 | -| 🔵 蓝底 | 用户触发 Skill | 15 | +| 🔵 蓝底 | 用户触发 Skill | 16 | | 🟢 绿底 | 系统自动 Skill | 2 | | 🩵 浅蓝底 | Agent（fork 路由目标） | 3 | | 🟡 黄底 | Hook 脚本 | 5 | -| 🟣 紫底 | Schema / Knowledge | 12 + 5 | +| 🟣 紫底 | Schema / Knowledge | 13 + 5 | ### 箭头说明 diff --git a/docs/features/pace-init.md b/docs/features/pace-init.md new file mode 100644 index 0000000..d4d45c4 --- /dev/null +++ b/docs/features/pace-init.md @@ -0,0 +1,530 @@ +# Project Initialization (`/pace-init`) + +`/pace-init` is the entry point for devpace — it creates the `.devpace/` directory that powers all other devpace features. What makes it unique is **lifecycle-aware initialization**: rather than asking the same questions regardless of project maturity, it detects whether a project is brand new, mid-development, or already released, and adapts its behavior accordingly. New projects get zero-question setup; mature projects get automatic version management and release tracking configuration. + +## Prerequisites + +| Requirement | Purpose | Required? | +|-------------|---------|:---------:| +| Project directory | Working directory for `.devpace/` creation | Yes | +| `git` initialized | Lifecycle detection uses git history signals | Recommended | +| Config files (package.json, pyproject.toml, etc.) | Auto-detect project name, description, and toolchain | Optional | + +> **Graceful degradation**: Non-git projects default to Stage A (new project) behavior. Missing config files simply mean more questions during setup. + +## Quick Start + +``` +1. /pace-init → Auto-detect lifecycle → generate .devpace/ +2. "帮我实现用户登录" → devpace auto-tracks as CR-001 +3. /pace-status → See project progress +``` + +For existing projects with requirements documents: + +``` +1. /pace-init --from prd.md → Parse doc → generate BR→PF→CR value tree +2. /pace-status tree → View the generated feature landscape +``` + +## Lifecycle Detection + +The core differentiator. `/pace-init` inspects the project to determine its maturity stage, then adapts every aspect of initialization. + +### Signal Detection + +| Signal | Detection method | Stage indicator | +|--------|-----------------|-----------------| +| Git commit count | `git rev-list --count HEAD` | 0-5 → new, 5-100 → mid-dev, 100+ → mature | +| Version tags | `git tag --list` | vX.Y.Z patterns → released | +| CHANGELOG.md | File existence | Present → released or near-release | +| Unmerged branches | `git branch --no-merged main` | >0 → active development | +| Deploy configs | fly.toml, k8s/, terraform/, etc. | Present → production-ready | +| Source file count | Language-specific file count | <10 → new, 10-100 → mid-dev, 100+ → mature | + +### Stage Determination (Priority Order) + +1. **Stage C (Released)**: Has version tags **or** CHANGELOG.md exists **or** deploy configs present +2. **Stage B (Mid-development)**: Not Stage C **and** (commits > 5 **or** unmerged branches **or** source files >= 10) +3. **Stage A (New project)**: Default when neither C nor B criteria are met + +Non-git directories default to Stage A. + +### What Each Stage Does + +| Capability | Stage A (New) | Stage B (Mid-dev) | Stage C (Released) | +|------------|:---:|:---:|:---:| +| Auto-detect name + description | ✅ | ✅ | ✅ | +| Zero-question setup (when inferrable) | ✅ | ✅ | ✅ | +| Directory structure → PF candidates | — | ✅ | ✅ | +| In-progress work from branches | — | ✅ | ✅ | +| Git strategy detection | — | ✅ | ✅ | +| README feature extraction | — | ✅ | ✅ | +| Version management auto-config | — | — | ✅ | +| Release history (DORA baseline) | — | — | ✅ | +| Environment list inference | — | — | ✅ | +| CHANGELOG parsing → BR/PF seeds | — | — | ✅ | +| pace-sync recommended (not optional) | — | — | ✅ | +| state.md complexity | Simple (5-8 lines) | Medium (10-12 lines) | Full (13-15 lines) | + +## Command Reference + +### Default: `/pace-init [project-name]` + +Lifecycle-aware minimal initialization. + +**Syntax**: `/pace-init [project-name]` + +Detects project lifecycle stage, collects minimal information (auto-inferred when possible), generates `.devpace/` with stage-appropriate configuration, injects devpace section into CLAUDE.md, runs post-init validation, and outputs contextual guidance. See [init-procedures-core.md](../../skills/pace-init/init-procedures-core.md) for detailed generation rules. + +**Output example** (Stage B project): +``` +检测到已有 47 次提交和 3 条活跃分支，已识别在研工作。 + +初始化完成： +.devpace/ +├── state.md — 项目状态（当前工作已预填） +├── project.md — 项目定义（PF 候选已从 src/ 推断） +├── backlog/ — CR 存放目录 +├── context.md — 技术约定（Git flow 检测） +└── rules/ + ├── workflow.md — 工作流规则 + └── checks.md — 质量检查（vitest + biome 已检测） + +✅ 所有文件校验通过 +CLAUDE.md — devpace section 已注入 + +试试说"帮我修复 XXX"或"帮我添加 XXX"，devpace 会自动追踪变更。 + +常用命令： +- 开始工作："帮我实现/修复/添加 XXX" +- 查看进度：/pace-status +- 管理变更：/pace-change +- 回顾总结：/pace-retro +``` + +### `full`: `/pace-init [project-name] full` + +Phased complete initialization with early exit support. + +**Syntax**: `/pace-init [project-name] full` + +Executes in 4 phases, each optional after Phase 1. Users can say "够了" at any point to skip remaining phases: + +1. **Foundation** (required): Name + description + environment detection → immediately usable `.devpace/` +2. **Business** (optional): "Define business objectives now? Or `/pace-retro` later" → OBJ + MoS + BR +3. **Release** (optional): "Configure release pipeline? Or edit integrations/config.md later" → release config +4. **Sync** (optional): "Configure GitHub sync? Or `/pace-sync setup` later" → external sync + +See [init-procedures-full.md](../../skills/pace-init/init-procedures-full.md) for detailed phase rules. + +### `--from`: `/pace-init --from ...` + +Document-driven initialization — auto-generates BR→PF→CR value tree from requirement documents. + +**Syntax**: `/pace-init [project-name] --from [--from ...]` + +Supports single files, directories (scans all .md/.txt files), and multiple files. Enhanced parsing handles user stories → BR, feature lists → PF tree, and OpenAPI/Swagger specs → PF grouped by resource. Results are shown for confirmation before writing to project.md. See [init-procedures-from.md](../../skills/pace-init/init-procedures-from.md) for parsing rules. + +**Output example**: +``` +从 prd.md 提取到以下功能树： + +BR-1: 用户管理（"让用户能安全地注册和登录系统"） +├── PF-1: 用户注册（邮箱+密码+验证） +│ ├── CR候选: 注册表单实现 +│ └── CR候选: 邮箱验证流程 +├── PF-2: 用户登录（JWT + 刷新令牌） +│ └── CR候选: 登录接口 + Token 管理 + +BR-2: 订单系统（"支持完整的购买流程"） +├── PF-3: 购物车 +└── PF-4: 支付集成 + +确认写入 project.md？[Y/n] +``` + +### `--verify`: `/pace-init --verify [--fix]` + +Health check for existing `.devpace/` directories. + +**Syntax**: `/pace-init --verify [--fix]` + +Iterates all `.devpace/` files, validates each against its corresponding schema, and outputs a health report. With `--fix`, auto-repairs structural issues (missing sections, format inconsistencies, version markers) without modifying semantic content. See [init-procedures-verify.md](../../skills/pace-init/init-procedures-verify.md) for the full validation checklist. + +**Output example**: +``` +.devpace/ 健康检查报告： +✅ state.md — 正常 +✅ project.md — 正常 +⚠️ rules/checks.md — 缺少 Gate 2 section（可自动修复） +❌ backlog/CR-001.md — 缺少"意图"字段（需人工处理） +✅ CLAUDE.md — devpace section 存在 + +总计：5 个文件，3 正常，1 可修复，1 需人工 +``` + +### `--reset`: `/pace-init --reset [--keep-insights]` + +Complete removal of `.devpace/` with safety checks. + +**Syntax**: `/pace-init --reset [--keep-insights]` + +Requires explicit confirmation before deletion. Removes `.devpace/` directory and cleans up the devpace section in CLAUDE.md (between `` and `` markers). Warns about external associations (GitHub Issues linked via sync-mapping). With `--keep-insights`, preserves `metrics/insights.md` as a cross-project asset. See [init-procedures-reset.md](../../skills/pace-init/init-procedures-reset.md) for detailed steps. + +### `--dry-run`: `/pace-init --dry-run [other-args]` + +Preview mode — runs all detection logic without writing any files. + +**Syntax**: `/pace-init [project-name] --dry-run` + +Executes the full lifecycle detection, toolchain analysis, and information gathering pipeline, then outputs a preview of what would be created. Particularly useful for Stage B/C projects to review auto-configuration results before committing. See [init-procedures-dryrun.md](../../skills/pace-init/init-procedures-dryrun.md) for output format. + +**Output example**: +``` +/pace-init 预览（dry-run 模式，不写入文件）： + +检测结果： +- 项目阶段：已有 120 次提交 + 5 个版本标签 +- 项目名称：my-api（来源：package.json） +- 技术栈：TypeScript + Express +- 工具链：vitest + biome + tsc + +将创建的文件： +.devpace/ +├── state.md — 项目状态（13 行，含版本信息） +├── project.md — 项目定义（PF 候选从 src/ 推断） +├── backlog/ — CR 存放目录 +├── context.md — 技术约定（5 条约定） +├── rules/ +│ ├── workflow.md — 工作流规则 +│ └── checks.md — 质量检查（4 条命令检查 + 2 条意图检查） +├── integrations/ +│ └── config.md — 版本管理 + 环境 + CI/CD +└── metrics/ + └── dashboard.md — DORA 基线（最近 5 次发布） + +CLAUDE.md — 将注入 devpace section + +确认初始化？运行 /pace-init my-api 开始。 +``` + +### `--export-template` / `--from-template` + +Template management for team-wide standardization. + +**Export syntax**: `/pace-init --export-template` + +Exports the current `.devpace/` configuration into a reusable `.devpace-template/` directory. Includes workflow.md, checks.md (with project-specific commands removed), context.md (with project-specific paths removed), and integrations/config.md. Designed for sharing quality standards across an organization's projects. + +**Apply syntax**: `/pace-init --from-template ` + +Initializes using a template as the base, overriding default templates with the team's configuration. Lifecycle detection and information collection still run normally; the template only provides workflow/checks/context/integrations defaults. + +Complementary to `--import-insights`: templates standardize *rules*, insights share *experience*. + +### `--import-insights` + +Import cross-project experience from another devpace project. + +**Syntax**: `/pace-init --import-insights ` + +Reads an exported insights file, downgrades confidence scores (×0.8), resets verification counts, skips preference-type entries, and deduplicates against existing insights. Can be used both during initial setup and on already-initialized projects. See [init-procedures-from.md](../../skills/pace-init/init-procedures-from.md) for processing rules. + +### `--interactive` + +Force interactive mode, overriding zero-question auto-detection. + +**Syntax**: `/pace-init [project-name] --interactive` + +Every auto-inferred value (project name, description, detected PF candidates, toolchain choices) is presented for confirmation before use. Useful when auto-detection might make incorrect assumptions or when you want full control over the initialization. + +## Usage Scenarios + +### Scenario 1: Brand New Project + +Starting fresh — no code yet, just an empty directory with `git init`. + +``` +You: /pace-init my-app +Claude: 这是一个全新项目，采用极简初始化。 + + 初始化完成： + .devpace/ + ├── state.md · project.md · backlog/ · rules/ + + ✅ 所有文件校验通过 + + 试试说"帮我实现 XXX"，我会自动创建第一个 CR 开始工作。 + +You: 帮我实现用户注册功能 +Claude: [Creates CR-001, begins development tracking automatically] +``` + +### Scenario 2: Mid-Development Project + +An existing project with 50+ commits and active branches, but no formal release yet. + +``` +You: /pace-init +Claude: 检测到已有 52 次提交和 2 条活跃分支，已识别在研工作。 + 项目名称：payment-service（来源：package.json） + 项目描述：A microservice for payment processing（来源：package.json） + + 识别到以下功能模块（从 src/ 目录结构）： + - auth/ → PF 候选: 认证模块 + - billing/ → PF 候选: 计费模块 + - webhook/ → PF 候选: Webhook 处理 + + 识别到 2 条未合并分支： + - feature/refund-api + - fix/timeout-handling + + 初始化完成 [...] + +You: 调整一下，webhook 不是独立功能，属于 billing 的一部分 +Claude: [Updates project.md accordingly] +``` + +### Scenario 3: Released Project with CI/CD + +A mature project with version tags, GitHub Actions, and deployment config. + +``` +You: /pace-init +Claude: 检测到已有 230 次提交和 8 个版本标签的项目，已自动配置版本管理和发布追踪。 + 当前版本：v2.3.1（tag 格式：vX.Y.Z） + 最近发布：v2.3.1 (02-20), v2.3.0 (02-15), v2.2.0 (01-28) + 环境：staging, production（来源：.env.staging, .env.production） + CI：GitHub Actions（push + PR trigger） + + 初始化完成： + .devpace/ + ├── state.md · project.md · backlog/ · context.md + ├── rules/ · integrations/config.md · metrics/dashboard.md + + 已发布项目通常需要外部同步，建议运行 /pace-sync setup 配置 CR 与 GitHub Issue 的同步。 +``` + +### Scenario 4: Preview Before Committing + +Unsure what `/pace-init` will create for your project? Preview first. + +``` +You: /pace-init --dry-run +Claude: [Full detection output + file tree preview, no files written] + +You: Looks good, go ahead +You: /pace-init +``` + +### Scenario 5: Health Check After Manual Edits + +You've been manually editing `.devpace/` files and want to verify everything is still valid. + +``` +You: /pace-init --verify +Claude: ⚠️ rules/checks.md — 缺少 Gate 2 section + +You: /pace-init --verify --fix +Claude: ✅ rules/checks.md — Gate 2 section 已补充 + ✅ 所有文件校验通过 +``` + +## Generated Files Reference + +| File | Description | When created | +|------|-------------|:------------:| +| `state.md` | Project status tracking (objective, current work, next step) | Always | +| `project.md` | Project definition with BR→PF→CR value tree | Always | +| `backlog/` | Directory for CR files | Always | +| `rules/workflow.md` | CR state machine and workflow rules | Always | +| `rules/checks.md` | Quality gate checks (toolchain-detected) | Always | +| `context.md` | Technical conventions and coding standards | Stage B/C or when ≥1 convention detected | +| `integrations/config.md` | CI/CD, version management, environment config | Stage C or when CI detected | +| `metrics/dashboard.md` | DORA metrics baseline from git history | Stage C only | +| `CLAUDE.md` (injection) | devpace section with `.devpace/` file reference table | Always | + +Files not created at init (on-demand): `iterations/`, `releases/`, `metrics/insights.md` — created when first needed by other commands. + +## Toolchain Detection + +`/pace-init` generates `checks.md` with precise commands matching the actual tools in your project, not generic suggestions. + +### Detection Matrix + +| Ecosystem | Signal | Detected tool | Generated command | +|-----------|--------|---------------|-------------------| +| Node.js | `vitest` in devDependencies | Vitest | `npx vitest run` | +| Node.js | `jest` in devDependencies | Jest | `npx jest` | +| Node.js | `@biomejs/biome` in devDependencies | Biome | `npx biome check .` | +| Node.js | `.eslintrc*` or `eslint.config.*` exists | ESLint | `npx eslint .` | +| Node.js | `typescript` in devDependencies | TypeScript | `npx tsc --noEmit` | +| Python | `[tool.pytest]` in pyproject.toml | pytest | `pytest` | +| Python | `[tool.ruff]` in pyproject.toml | Ruff | `ruff check .` | +| Python | `[tool.mypy]` in pyproject.toml | mypy | `mypy .` | +| Go | go.mod exists | Go test | `go test ./...` | +| Go | `.golangci.yml` exists | golangci-lint | `golangci-lint run` | +| Rust | Cargo.toml exists | Cargo | `cargo test` + `cargo clippy -- -D warnings` | + +When no specific tool is detected, generic placeholders are preserved for manual configuration. + +## CLAUDE.md Smart Merge + +`/pace-init` injects a devpace section into your project's `CLAUDE.md` using HTML comment markers for idempotent updates: + +```markdown + +# Project Name +> Project description +## 研发协作 +[...devpace file reference table...] + +``` + +**Merge behavior**: +- Markers present → replace content between markers (idempotent update) +- File exists, no markers → append marked section at end +- File doesn't exist → create new file with marked section + +Re-running `/pace-init` or upgrading devpace safely updates the section without affecting other CLAUDE.md content. + +## Integration with Other Commands + +| Command | Integration point | +|---------|-------------------| +| `/pace-dev` | Uses `rules/checks.md` generated by init for quality gates | +| `/pace-status` | Reads `state.md` and `project.md` created by init | +| `/pace-change` | Uses value tree in `project.md` for impact analysis | +| `/pace-retro` | Fills business objectives in `project.md` if still stub | +| `/pace-sync setup` | Proposed during init for Stage C projects and when git remote detected | +| `/pace-release` | Uses version management config in `integrations/config.md` | +| `/pace-plan` | Creates `iterations/current.md` (on-demand, not at init) | + +## Architecture (for Developers) + +### Skill File Architecture + +`/pace-init` uses a routing + procedure split pattern for token efficiency: + +| File | Lines | Purpose | +|------|------:|---------| +| `SKILL.md` | 62 | Routing layer — input/output/dispatch, loaded on every invocation | +| `init-procedures-core.md` | 387 | Shared core — lifecycle detection, Git strategy, minimal init, CLAUDE.md merge, validation, guidance, migration, quality check guidance, monorepo | +| `init-procedures-checks.md` | 84 | Toolchain detection reference — ecosystem-specific detection tables, default check suggestions, check format | +| `init-procedures-full.md` | 154 | `full` mode — environment probing, phased guidance, release config | +| `init-procedures-from.md` | 53 | `--from` / `--import-insights` — document parsing, experience import | +| `init-procedures-verify.md` | 54 | `--verify` — health check | +| `init-procedures-reset.md` | 31 | `--reset` — reset procedure | +| `init-procedures-dryrun.md` | 40 | `--dry-run` — preview mode | +| `init-procedures-template.md` | 25 | `--export-template` / `--from-template` — template management | + +Claude loads only the procedure files relevant to the invoked sub-command, reducing context window consumption compared to the previous monolithic design. + +### Lifecycle Detection Algorithm + +The detection uses a priority-based evaluation of 6 signals. Stage C takes highest priority (any release indicator triggers it), followed by Stage B (development activity), with Stage A as the default fallback. This ensures mature projects always get the richest auto-configuration even if some signals are ambiguous. + +``` +Signals collected (parallel): + commits ← git rev-list --count HEAD + tags ← git tag --list (filtered for version patterns) + deploy ← glob(fly.toml, app.yaml, serverless.yml, k8s/, terraform/) + branches← git branch --no-merged main | wc -l + sources ← count(*.js, *.ts, *.py, *.go, *.rs, *.java) + changelog ← exists(CHANGELOG.md) + +Stage determination: + if tags.match(version) OR changelog OR deploy.any → Stage C + elif commits > 5 OR branches > 0 OR sources >= 10 → Stage B + else → Stage A +``` + +### File Generation Pipeline + +``` +┌─────────────────────────┐ +│ Step 0: Routing │ +│ --verify/--reset/ │ +│ --dry-run flag │ +├─────────────────────────┤ +│ Step 1: Detection │ +│ Lifecycle + Info gather │ +│ (stage-adaptive) │ +├─────────────────────────┤ +│ Step 2: Generation │ +│ Templates + pre-fill │ +│ (stage-adaptive) │ +├─────────────────────────┤ +│ Step 3: CLAUDE.md │ +│ Smart merge (idempotent)│ +├─────────────────────────┤ +│ Step 4: Validation │ +│ Schema check + guidance │ +└─────────────────────────┘ +``` + +### Template System + +Templates live in `skills/pace-init/templates/` (12 files). Each template uses `{{PLACEHOLDER}}` syntax for dynamic content replacement. The generation rules in [init-procedures-core.md](../../skills/pace-init/init-procedures-core.md) define exactly which placeholders are replaced and with what values for each lifecycle stage. + +### Monorepo Support + +When monorepo signals are detected (`pnpm-workspace.yaml`, `nx.json`, `turbo.json`, `lerna.json`), the user chooses between: + +- **Single root `.devpace/`** (recommended for <5 packages): Standard init, `context.md` records monorepo structure +- **Root shared + per-package tracking** (for >=5 packages): Root gets `rules/` + `context.md`, each sub-package gets independent `state.md` + `project.md` + `backlog/` + +### Migration Framework + +Version detection via `` marker in `state.md`. When a lower version is detected, incremental migration segments execute (only-add, never-delete policy). Migration segments are appended to init-procedures-core.md as new versions ship. Each migration prompts user confirmation and provides rollback via `git revert`. + +## Degradation & Troubleshooting + +### Degradation Behavior + +| Condition | Behavior | +|-----------|----------| +| No `.git/` directory | Default to Stage A; skip all git-based detection | +| No config files (package.json, etc.) | Ask for project name and description manually | +| No CI/CD configuration detected | Skip `integrations/config.md` creation | +| Fewer than 1 convention detected | Skip `context.md` creation | +| Non-git project with `--from` | Full `--from` parsing works; lifecycle defaults to Stage A | +| `--verify` on missing `.devpace/` | Prompt to run `/pace-init` first | +| `--reset` with sync-mapping | Warn about external associations before deletion | + +### Common Issues + +| Issue | Cause | Solution | +|-------|-------|----------| +| Wrong lifecycle stage detected | Unusual git history pattern | Use `--interactive` to override auto-detection | +| checks.md has wrong test command | Tool detection mismatch | Edit `.devpace/rules/checks.md` directly | +| CLAUDE.md section duplicated | Markers were accidentally removed | Run `/pace-init` again (re-creates markers) | +| `--verify` reports many errors | Manual edits broke schema compliance | Run `--verify --fix` for auto-repair | +| Monorepo not detected | Non-standard workspace config | Use `--interactive` and configure manually | + +## Roadmap + +| Version | Features | Status | +|---------|----------|--------| +| v1.0.0 | Minimal init + full mode + environment detection | ✅ Released | +| v1.2.0 | Cross-project insights import (`--import-insights`) | ✅ Released | +| v1.5.0 | Lifecycle-aware init + `--verify`/`--reset`/`--dry-run` + `--from` enhanced + `--export-template` + Monorepo + CLAUDE.md smart merge + toolchain precision + contextual guidance | ✅ Current | + +## Related Resources + +- [User Guide — /pace-init section](../user-guide.md) — Quick reference for end users +- [SKILL.md](../../skills/pace-init/SKILL.md) — Skill definition (routing layer) +- [init-procedures-core.md](../../skills/pace-init/init-procedures-core.md) — Core execution rules (lifecycle, init, migration) +- [init-procedures-checks.md](../../skills/pace-init/init-procedures-checks.md) — Toolchain detection reference data +- [init-procedures-full.md](../../skills/pace-init/init-procedures-full.md) — Full mode execution rules +- [init-procedures-from.md](../../skills/pace-init/init-procedures-from.md) — Document-driven init and insights import +- [init-procedures-verify.md](../../skills/pace-init/init-procedures-verify.md) — Health check rules +- [init-procedures-reset.md](../../skills/pace-init/init-procedures-reset.md) — Reset procedure +- [init-procedures-dryrun.md](../../skills/pace-init/init-procedures-dryrun.md) — Preview mode rules +- [init-procedures-template.md](../../skills/pace-init/init-procedures-template.md) — Template management rules +- [state-format.md](../../knowledge/_schema/state-format.md) — State file schema +- [project-format.md](../../knowledge/_schema/project-format.md) — Project file schema +- [checks-format.md](../../knowledge/_schema/checks-format.md) — Quality checks schema +- [context-format.md](../../knowledge/_schema/context-format.md) — Technical conventions schema +- [devpace-rules.md](../../rules/devpace-rules.md) — Runtime behavior rules diff --git a/docs/features/pace-init_zh.md b/docs/features/pace-init_zh.md new file mode 100644 index 0000000..ce4499d --- /dev/null +++ b/docs/features/pace-init_zh.md @@ -0,0 +1,530 @@ +# 项目初始化（`/pace-init`） + +`/pace-init` 是 devpace 的入口——它创建 `.devpace/` 目录，驱动所有其他 devpace 功能。其核心差异是**生命周期感知初始化**：不是对所有项目千篇一律地提问，而是自动检测项目处于全新、开发中还是已发布阶段，据此适配初始化行为。新项目零提问启动；成熟项目自动配置版本管理和发布追踪。 + +## 前置条件 + +| 条件 | 用途 | 是否必须 | +|------|------|:--------:| +| 项目目录 | `.devpace/` 的创建位置 | 是 | +| `git` 已初始化 | 生命周期检测依赖 git 历史信号 | 推荐 | +| 配置文件（package.json、pyproject.toml 等） | 自动检测项目名称、描述和工具链 | 可选 | + +> **优雅降级**：非 git 项目默认按阶段 A（新项目）处理。缺少配置文件只意味着需要手动回答更多问题。 + +## 快速上手 + +``` +1. /pace-init → 自动检测生命周期 → 生成 .devpace/ +2. "帮我实现用户登录" → devpace 自动追踪为 CR-001 +3. /pace-status → 查看项目进度 +``` + +已有需求文档的项目： + +``` +1. /pace-init --from prd.md → 解析文档 → 生成 BR→PF→CR 价值功能树 +2. /pace-status tree → 查看生成的功能全景 +``` + +## 生命周期检测 + +核心差异化能力。`/pace-init` 检测项目成熟度阶段，据此适配初始化的方方面面。 + +### 信号检测 + +| 信号 | 检测方式 | 阶段指向 | +|------|---------|---------| +| Git commit 数量 | `git rev-list --count HEAD` | 0-5 → 新项目，5-100 → 开发中，100+ → 成熟 | +| 版本标签 | `git tag --list` | 匹配 vX.Y.Z 模式 → 已发布 | +| CHANGELOG.md | 文件存在性 | 存在 → 已发布或接近发布 | +| 未合并分支 | `git branch --no-merged main` | >0 → 有进行中工作 | +| 部署配置 | fly.toml、k8s/、terraform/ 等 | 存在 → 已上线 | +| 源文件数量 | 按语言统计源文件 | <10 → 新项目，10-100 → 开发中，100+ → 成熟 | + +### 阶段判定（按优先级） + +1. **阶段 C（已发布）**：有版本标签 **或** CHANGELOG.md 存在 **或** 有部署配置 +2. **阶段 B（开发中）**：不满足阶段 C **且**（commit 数 > 5 **或** 有未合并分支 **或** 源文件数 >= 10） +3. **阶段 A（新项目）**：不满足 C 和 B 条件时的默认值 + +非 git 目录默认为阶段 A。 + +### 各阶段行为对比 + +| 能力 | 阶段 A（新项目） | 阶段 B（开发中） | 阶段 C（已发布） | +|------|:---:|:---:|:---:| +| 自动检测名称 + 描述 | ✅ | ✅ | ✅ | +| 零提问启动（可推断时） | ✅ | ✅ | ✅ | +| 目录结构 → PF 候选 | — | ✅ | ✅ | +| 未合并分支 → 在研工作 | — | ✅ | ✅ | +| Git 分支策略检测 | — | ✅ | ✅ | +| README 功能提取 | — | ✅ | ✅ | +| 版本管理自动配置 | — | — | ✅ | +| 发布历史（DORA 基线） | — | — | ✅ | +| 环境列表推断 | — | — | ✅ | +| CHANGELOG 解析 → BR/PF 种子 | — | — | ✅ | +| pace-sync 推荐（非可选） | — | — | ✅ | +| state.md 复杂度 | 简单（5-8 行） | 中等（10-12 行） | 完整（13-15 行） | + +## 命令参考 + +### 默认模式：`/pace-init [项目名称]` + +生命周期感知的最小初始化。 + +**语法**：`/pace-init [项目名称]` + +检测项目生命周期阶段，收集最少信息（可推断时自动获取），生成按阶段适配的 `.devpace/`，向 CLAUDE.md 注入 devpace section，运行初始化后校验，输出情境化引导。详细生成规则见 [init-procedures-core.md](../../skills/pace-init/init-procedures-core.md)。 + +**输出示例**（阶段 B 项目）： +``` +检测到已有 47 次提交和 3 条活跃分支，已识别在研工作。 + +初始化完成： +.devpace/ +├── state.md — 项目状态（当前工作已预填） +├── project.md — 项目定义（PF 候选已从 src/ 推断） +├── backlog/ — CR 存放目录 +├── context.md — 技术约定（Git flow 检测） +└── rules/ + ├── workflow.md — 工作流规则 + └── checks.md — 质量检查（vitest + biome 已检测） + +✅ 所有文件校验通过 +CLAUDE.md — devpace section 已注入 + +试试说"帮我修复 XXX"或"帮我添加 XXX"，devpace 会自动追踪变更。 + +常用命令： +- 开始工作："帮我实现/修复/添加 XXX" +- 查看进度：/pace-status +- 管理变更：/pace-change +- 回顾总结：/pace-retro +``` + +### `full` 模式：`/pace-init [项目名称] full` + +分阶段完整初始化，支持提前退出。 + +**语法**：`/pace-init [项目名称] full` + +按 4 个阶段引导，第 1 阶段后每个阶段均可选。用户可随时说"够了"跳过剩余阶段： + +1. **基础阶段**（必须）：项目名 + 描述 + 环境检测 → 立即生成可用 .devpace/ +2. **业务阶段**（可选）："要现在定义业务目标和成效指标吗？可稍后 /pace-retro 补充" → OBJ + MoS + BR +3. **发布阶段**（可选）："检测到 [CI 工具]，要配置发布流程吗？可稍后编辑 integrations/config.md" → 发布配置 +4. **同步阶段**（可选）："检测到 GitHub 仓库，要配置外部同步吗？可稍后 /pace-sync setup" → 同步配置 + +详细阶段规则见 [init-procedures-full.md](../../skills/pace-init/init-procedures-full.md)。 + +### `--from` 模式：`/pace-init --from <路径>...` + +文档驱动初始化——从需求文档自动生成 BR→PF→CR 价值功能树。 + +**语法**：`/pace-init [项目名称] --from <路径> [--from <路径2>...]` + +支持单文件、目录（扫描所有 .md/.txt 文件）和多文件。增强解析：用户故事 → BR、功能列表 → PF 树、OpenAPI/Swagger 规格 → 按资源分组的 PF。解析结果先展示确认再写入 project.md。详细解析规则见 [init-procedures-from.md](../../skills/pace-init/init-procedures-from.md)。 + +**输出示例**： +``` +从 prd.md 提取到以下功能树： + +BR-1: 用户管理（"让用户能安全地注册和登录系统"） +├── PF-1: 用户注册（邮箱+密码+验证） +│ ├── CR候选: 注册表单实现 +│ └── CR候选: 邮箱验证流程 +├── PF-2: 用户登录（JWT + 刷新令牌） +│ └── CR候选: 登录接口 + Token 管理 + +BR-2: 订单系统（"支持完整的购买流程"） +├── PF-3: 购物车 +└── PF-4: 支付集成 + +确认写入 project.md？[Y/n] +``` + +### `--verify` 健康检查：`/pace-init --verify [--fix]` + +校验已有 `.devpace/` 目录的完整性。 + +**语法**：`/pace-init --verify [--fix]` + +遍历 `.devpace/` 所有文件，按对应 Schema 逐一校验，输出健康报告。加 `--fix` 自动修复结构问题（缺失 section、格式不一致、版本标记），不修改语义内容。详细校验清单见 [init-procedures-verify.md](../../skills/pace-init/init-procedures-verify.md)。 + +**输出示例**： +``` +.devpace/ 健康检查报告： +✅ state.md — 正常 +✅ project.md — 正常 +⚠️ rules/checks.md — 缺少 Gate 2 section（可自动修复） +❌ backlog/CR-001.md — 缺少"意图"字段（需人工处理） +✅ CLAUDE.md — devpace section 存在 + +总计：5 个文件，3 正常，1 可修复，1 需人工 +``` + +### `--reset` 重置：`/pace-init --reset [--keep-insights]` + +完全删除 `.devpace/`，含安全确认。 + +**语法**：`/pace-init --reset [--keep-insights]` + +删除前需明确确认。删除 `.devpace/` 目录并清理 CLAUDE.md 中的 devpace section（`` 到 `` 区间）。若存在外部关联（sync-mapping 关联的 GitHub Issues），会提示需手动处理。`--keep-insights` 保留 `metrics/insights.md`（经验是跨项目资产）。详细步骤见 [init-procedures-reset.md](../../skills/pace-init/init-procedures-reset.md)。 + +### `--dry-run` 预览：`/pace-init --dry-run [其他参数]` + +预览模式——执行全部检测逻辑，不写入任何文件。 + +**语法**：`/pace-init [项目名称] --dry-run` + +运行完整的生命周期检测、工具链分析和信息收集流程，然后输出将创建的文件预览。特别适合阶段 B/C 项目在确认前查看自动配置结果。详细输出格式见 [init-procedures-dryrun.md](../../skills/pace-init/init-procedures-dryrun.md)。 + +**输出示例**： +``` +/pace-init 预览（dry-run 模式，不写入文件）： + +检测结果： +- 项目阶段：已有 120 次提交 + 5 个版本标签 +- 项目名称：my-api（来源：package.json） +- 技术栈：TypeScript + Express +- 工具链：vitest + biome + tsc + +将创建的文件： +.devpace/ +├── state.md — 项目状态（13 行，含版本信息） +├── project.md — 项目定义（PF 候选从 src/ 推断） +├── backlog/ — CR 存放目录 +├── context.md — 技术约定（5 条约定） +├── rules/ +│ ├── workflow.md — 工作流规则 +│ └── checks.md — 质量检查（4 条命令检查 + 2 条意图检查） +├── integrations/ +│ └── config.md — 版本管理 + 环境 + CI/CD +└── metrics/ + └── dashboard.md — DORA 基线（最近 5 次发布） + +CLAUDE.md — 将注入 devpace section + +确认初始化？运行 /pace-init my-api 开始。 +``` + +### `--export-template` / `--from-template` 模板管理 + +团队级标准化的模板管理。 + +**导出语法**：`/pace-init --export-template` + +将当前 `.devpace/` 配置导出为可复用的 `.devpace-template/` 目录。包含 workflow.md、checks.md（移除项目特定命令）、context.md（移除项目特定路径）和 integrations/config.md。用于在组织内多个项目间共享质量标准。 + +**应用语法**：`/pace-init --from-template <路径>` + +使用模板作为基础进行初始化，模板中的配置覆盖默认模板。生命周期检测和信息收集照常运行；模板仅提供 workflow/checks/context/integrations 的默认值。 + +与 `--import-insights` 互补：模板标准化**规范**，insights 共享**经验**。 + +### `--import-insights` 跨项目经验导入 + +从另一个 devpace 项目导入经验。 + +**语法**：`/pace-init --import-insights <路径>` + +读取导出的 insights 文件，置信度降级（×0.8），验证次数重置，跳过偏好类型条目，与现有 insights 去重。可在初始化时使用，也可在已初始化的项目上独立使用。详细处理规则见 [init-procedures-from.md](../../skills/pace-init/init-procedures-from.md)。 + +### `--interactive` 交互模式 + +强制交互模式，覆盖零提问的自动检测行为。 + +**语法**：`/pace-init [项目名称] --interactive` + +所有自动推断的值（项目名称、描述、PF 候选、工具链选择）都会逐项展示确认后再使用。适用于自动检测可能不准确或你希望完全控制初始化过程的场景。 + +## 使用场景 + +### 场景 1：全新项目 + +从零开始——一个空目录，刚执行 `git init`。 + +``` +你： /pace-init my-app +Claude: 这是一个全新项目，采用极简初始化。 + + 初始化完成： + .devpace/ + ├── state.md · project.md · backlog/ · rules/ + + ✅ 所有文件校验通过 + + 试试说"帮我实现 XXX"，我会自动创建第一个 CR 开始工作。 + +你： 帮我实现用户注册功能 +Claude: [创建 CR-001，自动开始追踪开发进度] +``` + +### 场景 2：开发中项目 + +已有 50+ 次提交和活跃分支的项目，但尚未正式发布。 + +``` +你： /pace-init +Claude: 检测到已有 52 次提交和 2 条活跃分支，已识别在研工作。 + 项目名称：payment-service（来源：package.json） + 项目描述：A microservice for payment processing（来源：package.json） + + 识别到以下功能模块（从 src/ 目录结构）： + - auth/ → PF 候选: 认证模块 + - billing/ → PF 候选: 计费模块 + - webhook/ → PF 候选: Webhook 处理 + + 识别到 2 条未合并分支： + - feature/refund-api + - fix/timeout-handling + + 初始化完成 [...] + +你： 调整一下，webhook 不是独立功能，属于 billing 的一部分 +Claude: [更新 project.md，将 webhook 归入 billing 模块] +``` + +### 场景 3：已发布项目（含 CI/CD） + +成熟项目，有版本标签、GitHub Actions 和部署配置。 + +``` +你： /pace-init +Claude: 检测到已有 230 次提交和 8 个版本标签的项目，已自动配置版本管理和发布追踪。 + 当前版本：v2.3.1（tag 格式：vX.Y.Z） + 最近发布：v2.3.1 (02-20), v2.3.0 (02-15), v2.2.0 (01-28) + 环境：staging, production（来源：.env.staging, .env.production） + CI：GitHub Actions（push + PR trigger） + + 初始化完成： + .devpace/ + ├── state.md · project.md · backlog/ · context.md + ├── rules/ · integrations/config.md · metrics/dashboard.md + + 已发布项目通常需要外部同步，建议运行 /pace-sync setup 配置。 +``` + +### 场景 4：初始化前预览 + +不确定 `/pace-init` 会创建什么？先预览。 + +``` +你： /pace-init --dry-run +Claude: [完整检测输出 + 文件树预览，不写入文件] + +你： 看起来没问题，执行吧 +你： /pace-init +``` + +### 场景 5：手动编辑后健康检查 + +手动编辑了 `.devpace/` 文件，想验证一切是否仍然有效。 + +``` +你： /pace-init --verify +Claude: ⚠️ rules/checks.md — 缺少 Gate 2 section + +你： /pace-init --verify --fix +Claude: ✅ rules/checks.md — Gate 2 section 已补充 + ✅ 所有文件校验通过 +``` + +## 生成文件参考 + +| 文件 | 说明 | 创建时机 | +|------|------|:--------:| +| `state.md` | 项目状态追踪（目标、当前工作、下一步） | 始终创建 | +| `project.md` | 项目定义，含 BR→PF→CR 价值功能树 | 始终创建 | +| `backlog/` | CR 文件存放目录 | 始终创建 | +| `rules/workflow.md` | CR 状态机和工作流规则 | 始终创建 | +| `rules/checks.md` | 质量门检查（工具链精准检测） | 始终创建 | +| `context.md` | 技术约定和编码规范 | 阶段 B/C 或检测到 ≥1 条约定时 | +| `integrations/config.md` | CI/CD、版本管理、环境配置 | 阶段 C 或检测到 CI 时 | +| `metrics/dashboard.md` | DORA 度量基线（从 git 历史提取） | 仅阶段 C | +| `CLAUDE.md`（注入） | devpace section，含 `.devpace/` 文件参考表 | 始终注入 | + +初始化时**不创建**的文件（按需创建）：`iterations/`、`releases/`、`metrics/insights.md` — 在首次被其他命令使用时自动创建。 + +## 工具链检测 + +`/pace-init` 生成的 `checks.md` 包含精准匹配项目实际工具的命令，而非笼统的通用建议。 + +### 检测矩阵 + +| 生态系统 | 检测信号 | 识别工具 | 生成命令 | +|---------|---------|---------|---------| +| Node.js | devDependencies 含 `vitest` | Vitest | `npx vitest run` | +| Node.js | devDependencies 含 `jest` | Jest | `npx jest` | +| Node.js | devDependencies 含 `@biomejs/biome` | Biome | `npx biome check .` | +| Node.js | `.eslintrc*` 或 `eslint.config.*` 存在 | ESLint | `npx eslint .` | +| Node.js | devDependencies 含 `typescript` | TypeScript | `npx tsc --noEmit` | +| Python | pyproject.toml 含 `[tool.pytest]` | pytest | `pytest` | +| Python | pyproject.toml 含 `[tool.ruff]` | Ruff | `ruff check .` | +| Python | pyproject.toml 含 `[tool.mypy]` | mypy | `mypy .` | +| Go | go.mod 存在 | Go test | `go test ./...` | +| Go | `.golangci.yml` 存在 | golangci-lint | `golangci-lint run` | +| Rust | Cargo.toml 存在 | Cargo | `cargo test` + `cargo clippy -- -D warnings` | + +未检测到具体工具时，保留通用占位符供手动配置。 + +## CLAUDE.md 智能合并 + +`/pace-init` 使用 HTML 注释标记向项目 `CLAUDE.md` 注入 devpace section，实现幂等更新： + +```markdown + +# 项目名称 +> 项目定位 +## 研发协作 +[...devpace 文件参考表...] + +``` + +**合并行为**： +- 已有标记 → 替换标记区间内的内容（幂等更新） +- 文件存在但无标记 → 末尾追加带标记的 section +- 文件不存在 → 创建新文件，包含标记 section + +重新运行 `/pace-init` 或升级 devpace 版本时，会安全更新该 section，不影响 CLAUDE.md 的其他内容。 + +## 与其他命令的集成 + +| 命令 | 集成点 | +|------|--------| +| `/pace-dev` | 使用 init 生成的 `rules/checks.md` 执行质量门 | +| `/pace-status` | 读取 init 创建的 `state.md` 和 `project.md` | +| `/pace-change` | 使用 `project.md` 中的价值功能树进行影响分析 | +| `/pace-retro` | project.md 仍为桩状态时引导填充业务目标 | +| `/pace-sync setup` | 阶段 C 项目或检测到 git remote 时在 init 中推荐 | +| `/pace-release` | 使用 `integrations/config.md` 中的版本管理配置 | +| `/pace-plan` | 创建 `iterations/current.md`（按需创建，不在 init 时） | + +## 架构说明（开发者向） + +### Skill 文件架构 + +`/pace-init` 使用路由+规程分拆模式优化 Token 效率： + +| 文件 | 行数 | 职责 | +|------|-----:|------| +| `SKILL.md` | 62 | 路由层——输入/输出/分发，每次调用时加载 | +| `init-procedures-core.md` | 387 | 共享核心——生命周期检测、Git 策略、最小初始化、CLAUDE.md 合并、校验、引导、迁移、质量检查引导、Monorepo | +| `init-procedures-checks.md` | 84 | 工具链检测参考——生态系统精准检测表、默认检查项建议、检查项格式 | +| `init-procedures-full.md` | 154 | `full` 模式——环境探测、分阶段引导、发布配置收集 | +| `init-procedures-from.md` | 53 | `--from` / `--import-insights`——文档解析、经验导入 | +| `init-procedures-verify.md` | 54 | `--verify`——健康检查 | +| `init-procedures-reset.md` | 31 | `--reset`——重置流程 | +| `init-procedures-dryrun.md` | 40 | `--dry-run`——预览模式 | +| `init-procedures-template.md` | 25 | `--export-template` / `--from-template`——模板管理 | + +Claude 仅加载与调用子命令相关的规程文件，相比之前的单体设计减少了上下文窗口消耗。 + +### 生命周期检测算法 + +检测使用 6 个信号的基于优先级的评估。阶段 C 拥有最高优先级（任何发布指标都触发），其次是阶段 B（开发活动），阶段 A 是默认兜底。这确保成熟项目始终获得最丰富的自动配置，即使某些信号模糊。 + +``` +信号收集（并行）： + commits ← git rev-list --count HEAD + tags ← git tag --list（筛选版本模式） + deploy ← glob(fly.toml, app.yaml, serverless.yml, k8s/, terraform/) + branches ← git branch --no-merged main | wc -l + sources ← count(*.js, *.ts, *.py, *.go, *.rs, *.java) + changelog← exists(CHANGELOG.md) + +阶段判定： + if tags.match(version) OR changelog OR deploy.any → 阶段 C + elif commits > 5 OR branches > 0 OR sources >= 10 → 阶段 B + else → 阶段 A +``` + +### 文件生成管道 + +``` +┌─────────────────────────┐ +│ Step 0：路由 │ +│ --verify/--reset/ │ +│ --dry-run 标志 │ +├─────────────────────────┤ +│ Step 1：检测 │ +│ 生命周期 + 信息收集 │ +│ （按阶段适配） │ +├─────────────────────────┤ +│ Step 2：生成 │ +│ 模板 + 预填充 │ +│ （按阶段适配） │ +├─────────────────────────┤ +│ Step 3：CLAUDE.md │ +│ 智能合并（幂等） │ +├─────────────────────────┤ +│ Step 4：校验 │ +│ Schema 检查 + 情境引导 │ +└─────────────────────────┘ +``` + +### 模板系统 + +模板存放在 `skills/pace-init/templates/`（12 个文件）。每个模板使用 `{{PLACEHOLDER}}` 语法进行动态内容替换。[init-procedures-core.md](../../skills/pace-init/init-procedures-core.md) 中的生成规则定义了每个生命周期阶段替换哪些占位符及其值。 + +### Monorepo 支持 + +检测到 monorepo 信号（`pnpm-workspace.yaml`、`nx.json`、`turbo.json`、`lerna.json`）时，用户选择： + +- **根目录单一 `.devpace/`**（推荐 <5 个子包）：标准初始化，`context.md` 记录 monorepo 结构 +- **根共享 + 子包独立追踪**（≥5 个子包）：根目录放 `rules/` + `context.md`，每个子包独立 `state.md` + `project.md` + `backlog/` + +### 迁移框架 + +通过 `state.md` 末尾的 `` 标记检测版本。检测到低版本时执行增量迁移段（只添加不删除策略）。新版本发布时在 init-procedures-core.md 中追加迁移段。每次迁移提示用户确认，支持通过 `git revert` 回滚。 + +## 降级行为与故障排除 + +### 降级行为 + +| 条件 | 行为 | +|------|------| +| 无 `.git/` 目录 | 默认阶段 A；跳过所有 git 相关检测 | +| 无配置文件（package.json 等） | 手动询问项目名称和描述 | +| 未检测到 CI/CD 配置 | 跳过 `integrations/config.md` 创建 | +| 检测到的约定不足 1 条 | 跳过 `context.md` 创建 | +| 非 git 项目使用 `--from` | `--from` 解析正常工作；生命周期默认阶段 A | +| `--verify` 但 `.devpace/` 不存在 | 提示先运行 `/pace-init` | +| `--reset` 时存在 sync-mapping | 删除前警告外部关联 | + +### 常见问题 + +| 问题 | 原因 | 解决方案 | +|------|------|---------| +| 生命周期阶段判定不准 | 异常的 git 历史模式 | 使用 `--interactive` 覆盖自动检测 | +| checks.md 测试命令有误 | 工具检测不匹配 | 直接编辑 `.devpace/rules/checks.md` | +| CLAUDE.md section 重复 | 标记被意外删除 | 重新运行 `/pace-init`（重新创建标记） | +| `--verify` 报大量错误 | 手动编辑破坏了 Schema 合规性 | 运行 `--verify --fix` 自动修复 | +| Monorepo 未被识别 | 非标准的 workspace 配置 | 使用 `--interactive` 手动配置 | + +## 路线图 + +| 版本 | 功能 | 状态 | +|------|------|------| +| v1.0.0 | 最小初始化 + full 模式 + 环境探测 | ✅ 已发布 | +| v1.2.0 | 跨项目经验导入（`--import-insights`） | ✅ 已发布 | +| v1.5.0 | 生命周期感知 + `--verify`/`--reset`/`--dry-run` + `--from` 增强 + `--export-template` + Monorepo + CLAUDE.md 智能合并 + 工具链精准检测 + 情境化引导 | ✅ 当前 | + +## 相关资源 + +- [用户指南 — /pace-init 章节](../user-guide.md) — 快速参考 +- [SKILL.md](../../skills/pace-init/SKILL.md) — Skill 定义（路由层） +- [init-procedures-core.md](../../skills/pace-init/init-procedures-core.md) — 核心执行规程（生命周期、初始化、迁移） +- [init-procedures-checks.md](../../skills/pace-init/init-procedures-checks.md) — 工具链检测参考数据 +- [init-procedures-full.md](../../skills/pace-init/init-procedures-full.md) — full 模式执行规程 +- [init-procedures-from.md](../../skills/pace-init/init-procedures-from.md) — 文档驱动初始化和经验导入 +- [init-procedures-verify.md](../../skills/pace-init/init-procedures-verify.md) — 健康检查规程 +- [init-procedures-reset.md](../../skills/pace-init/init-procedures-reset.md) — 重置流程 +- [init-procedures-dryrun.md](../../skills/pace-init/init-procedures-dryrun.md) — 预览模式规程 +- [init-procedures-template.md](../../skills/pace-init/init-procedures-template.md) — 模板管理规程 +- [state-format.md](../../knowledge/_schema/state-format.md) — 状态文件 Schema +- [project-format.md](../../knowledge/_schema/project-format.md) — 项目文件 Schema +- [checks-format.md](../../knowledge/_schema/checks-format.md) — 质量检查 Schema +- [context-format.md](../../knowledge/_schema/context-format.md) — 技术约定 Schema +- [devpace-rules.md](../../rules/devpace-rules.md) — 运行时行为规则 diff --git a/docs/features/pace-sync.md b/docs/features/pace-sync.md new file mode 100644 index 0000000..7924886 --- /dev/null +++ b/docs/features/pace-sync.md @@ -0,0 +1,300 @@ +# External Tool Sync (`/pace-sync`) + +devpace is a closed system — CR states live exclusively inside `.devpace/`. `/pace-sync` bridges devpace with GitHub Issues through **semantic-level synchronization**: rather than mechanically mapping field A to field B, Claude understands "this change request is being implemented" and generates the corresponding external operation. v1.5.0 ships as a **push-only MVP**; bidirectional sync is planned for Phase 20. + +## Prerequisites + +| Requirement | Purpose | Required? | +|-------------|---------|:---------:| +| `gh` CLI | GitHub API operations (labels, comments, issue state) | Recommended | +| `git remote` configured | Auto-detect repository owner/name during setup | Yes | +| `.devpace/` initialized | Core devpace project structure | Yes | + +> **Graceful degradation**: If `gh` CLI is not installed, `setup` still generates the configuration file (marked as "unverified"). `push` and `status` require `gh` to function. + +## Quick Start + +``` +1. /pace-sync setup → Detects git remote → generates sync-mapping.md +2. /pace-sync link CR-003 #42 → Associates CR-003 with GitHub Issue #42 +3. /pace-sync push → Pushes state → Issue #42 labels updated +``` + +After setup, the sync-push advisory hook automatically reminds you to push after CR state changes. + +## Command Reference + +### `setup` + +Guided configuration wizard. + +**Syntax**: `/pace-sync setup` + +Detects `git remote`, verifies `gh` CLI connectivity, and generates `.devpace/integrations/sync-mapping.md` per the [sync-mapping-format.md](../../knowledge/_schema/sync-mapping-format.md) schema. See [sync-procedures.md §2](../../skills/pace-sync/sync-procedures.md) for detailed steps. + +**Output example**: +``` +Sync configured: +- Platform: GitHub (myorg/myrepo) +- Sync mode: push +- Connection: ✅ verified +Next: use /pace-sync link CR-xxx #IssueNumber to associate change requests +``` + +**Degradation**: When `gh` is unavailable, the config file is still created with "connection unverified" status. + +### `link` + +Associate a CR with an external entity. + +**Syntax**: `/pace-sync link <#ExternalID>` (e.g., `link CR-003 #42`) + +Verifies both the CR and external entity exist, writes the association into the CR file and sync-mapping.md. See [sync-procedures.md §3](../../skills/pace-sync/sync-procedures.md) for detailed steps. + +**Error handling**: CR not found, external entity not found → prompts user. CR already linked → confirms before overwriting. + +### `push` + +Push devpace state to external tools. + +**Syntax**: `/pace-sync push [CR-ID] [--dry-run]` + +Pushes CR state to external platform for one or all linked CRs. With `--dry-run`, previews actions without executing. Compares local vs external state and only updates when inconsistent. See [sync-procedures.md §4](../../skills/pace-sync/sync-procedures.md) for detailed steps. + +**Output example**: +``` +| CR | State | External action | Result | +|--------|------------|----------------------------|--------| +| CR-003 | developing | Add label: in-progress | ✅ | +| CR-005 | merged | Close Issue #18 + add done | ✅ | +``` + +### `unlink` + +Remove the association between a CR and its external entity. + +**Syntax**: `/pace-sync unlink ` + +Clears the external association field from the CR file and removes the record from sync-mapping.md. See [sync-procedures.md §5.5](../../skills/pace-sync/sync-procedures.md) for detailed steps. + +**Error handling**: CR has no association or doesn't exist → prompts user. + +### `create` + +Create an external Issue from CR metadata and automatically link it. + +**Syntax**: `/pace-sync create ` + +Reads CR metadata (title, intent, acceptance criteria), creates an Issue with the appropriate state label, and auto-links via the `link` flow. See [sync-procedures.md §5.6](../../skills/pace-sync/sync-procedures.md) for detailed steps. + +**Error handling**: CR already linked → confirms before overriding. `gh` unavailable → prompts installation. CR doesn't exist → prompts user. + +### `status` + +View sync status for all linked CRs. + +**Syntax**: `/pace-sync status` + +Reads all association records, compares devpace vs external state, and outputs a consistency table. See [sync-procedures.md §5](../../skills/pace-sync/sync-procedures.md) for detailed steps. + +**Output example**: +``` +| CR | External | devpace | External | Consistent | Last sync | +|--------|----------|------------|---------------|------------|--------------| +| CR-003 | #42 | developing | in-progress | ✅ | 02-25 10:30 | +| CR-005 | #18 | merged | open | ❌ push | 02-24 15:00 | +``` + +## State Mapping + +devpace CR states map to GitHub labels (e.g., `developing` → `in-progress`, `merged` → close Issue + `done`). The full mapping table is defined in [sync-mapping-format.md](../../knowledge/_schema/sync-mapping-format.md) (schema authority) and [sync-adapter-github.md](../../skills/pace-sync/sync-adapter-github.md) (GitHub-specific operations). + +The effective sync direction is the intersection of the platform sync mode and the per-state direction. In push mode, even bidirectional states only execute the push direction. + +## Usage Scenarios + +### Scenario 1: First-time Configuration + +You have an existing devpace project and want to start syncing with GitHub Issues. + +``` +You: /pace-sync setup +Claude: Detected repository: myorg/my-project + Sync mode: push (recommended for MVP) + Conflict strategy: ask-user + Verify connection? [Y/n] + +You: Y +Claude: ✅ Connection verified + Config written to .devpace/integrations/sync-mapping.md + + Next: /pace-sync link CR-xxx #IssueNumber +``` + +### Scenario 2: Daily Development Push + +After a `/pace-dev` session transitions CR-003 from `created` to `developing`, the sync-push hook detects the actual state transition and reminds you: + +``` +Hook: devpace:sync-push CR-003 state transition: created→developing, linked to github#42. + Consider running /pace-sync push to sync status. + +You: /pace-sync push CR-003 +Claude: | CR | State | Action | Result | + |--------|------------|----------------------|--------| + | CR-003 | developing | Add label in-progress| ✅ | +``` + +### Scenario 3: Consistency Check + +Before a release, verify all CRs are in sync: + +``` +You: /pace-sync status +Claude: | CR | External | devpace | External | Match | Last sync | + |--------|----------|------------|---------------|-------|-------------| + | CR-003 | #42 | merged | done (closed) | ✅ | 02-25 14:00 | + | CR-005 | #18 | developing | backlog | ❌ | 02-24 15:00 | + + 1 CR out of sync. Run /pace-sync push to update. +``` + +## Configuration Reference + +The sync configuration lives in `.devpace/integrations/sync-mapping.md`, following the [sync-mapping-format.md](../../knowledge/_schema/sync-mapping-format.md) schema. + +### Platform + +```markdown +## Platform + +- **Type**: github +- **Connection**: myorg/myrepo +- **Sync mode**: push +- **Conflict strategy**: ask-user +``` + +### State Mapping Table + +Customizable per-project. The default mapping can be modified to use your own label names: + +```markdown +| devpace state | External state | Direction | Notes | +|---------------|------------------------|-----------|--------------------| +| created | open + my-custom-label | ↔ | Custom label name | +``` + +The [sync-mapping-format.md](../../knowledge/_schema/sync-mapping-format.md) schema defines all configuration sections: platform fields, state mapping, entity mapping, gate result sync, and association records. + +## Integration with Other Commands + +`/pace-dev` and `/pace-change` trigger the sync-push advisory hook after CR state changes. `/pace-status` displays sync status alongside CR info. Future integrations include `/pace-release` and `/pace-review` (Phase 19). See [sync-procedures.md §7](../../skills/pace-sync/sync-procedures.md) for the full integration matrix. + +## Architecture (for Developers) + +### Semantic Bridge Concept + +Traditional integrations map "field A → field B" mechanically. devpace takes a fundamentally different approach: + +- **Semantic understanding**: CR `developing` is not simply mapped to a GitHub `in-progress` label. Claude understands "this change request is being implemented" and generates the corresponding operation. +- **Contextual actions**: An external PR merge doesn't just trigger a state change — Claude understands "code has been merged, quality gate check is needed." +- **Intelligent conflict resolution**: Conflicts are not resolved by "who wins" rules, but by Claude analyzing context from both sides and providing recommendations. + +### Layered Architecture + +``` +┌──────────────────────────────────┐ +│ pace-sync Skill Layer │ +│ setup/link/push/unlink/create/ │ +├──────────────────────────────────┤ +│ Operation Orchestration │ +│ sync-procedures.md │ +│ (platform-agnostic steps) │ +├──────────────────────────────────┤ +│ Platform Adapters │ +│ sync-adapter-github.md │ +│ sync-adapter-linear.md (P19) │ +├──────────────────────────────────┤ +│ Existing MCP/CLI (no custom) │ +│ gh CLI / Linear MCP / Jira MCP │ +├──────────────────────────────────┤ +│ Configuration Layer │ +│ sync-mapping.md + config.md │ +└──────────────────────────────────┘ +``` + +**Key decisions**: +- devpace does **not** build custom MCP Servers — GitHub, Linear, Jira, and GitLab all have mature existing tools. devpace focuses exclusively on the semantic orchestration layer. +- Platform adapters are split into per-platform files (e.g., `sync-adapter-github.md`). `sync-procedures.md` uses operation semantics (e.g., "verify connection", "update status marker") that reference the adapter's operation table. Adding a new platform requires zero changes to procedures (OCP). + +### Adapter Routing + +| Platform | Adapter file | Tool | Status | +|----------|-------------|------|--------| +| GitHub | sync-adapter-github.md | gh CLI | Available | +| Linear | sync-adapter-linear.md | MCP | Phase 19 | +| Jira | sync-adapter-jira.md | MCP/CLI | Phase 19+ | + +MVP defaults to GitHub via `gh` CLI (zero additional dependencies). Subcommand steps use operation semantics; Claude loads the corresponding adapter file based on the platform field in sync-mapping.md. + +### Extension Points + +To add a new platform adapter: + +1. Create `sync-adapter-{platform}.md` with operation table, state update strategy, and platform-specific rules +2. Add platform type to sync-mapping-format.md (`Type` field values) +3. Add routing entry to `sync-procedures.md §1` adapter route table +4. No changes needed to sync-procedures.md subcommand steps or SKILL.md (OCP verified) + +## Degradation & Troubleshooting + +### Degradation Behavior + +All subcommands gracefully degrade: missing sync-mapping.md guides to `setup`, unavailable `gh` CLI allows config creation but blocks push/status, and missing associations are skipped silently. The full degradation matrix is defined in [sync-mapping-format.md](../../knowledge/_schema/sync-mapping-format.md). + +### Common Issues + +| Issue | Cause | Solution | +|-------|-------|----------| +| `gh auth` error | Not logged in | Run `gh auth login` | +| Label not found | Custom labels not created | Labels are auto-created on first push | +| Wrong repository | Multiple remotes | Re-run `setup` to select correct remote | +| Stale sync state | Manual external changes | Run `status` to detect drift, then `push` | + +### Advisory Hooks (Dual-Layer) + +Two PostToolUse hooks work together to ensure external sync on CR state transitions: + +**sync-push.mjs** — State change detection via file-based cache (`.devpace/.sync-state-cache`). Only fires on **actual state transitions**, not on every CR write (eliminates noise). Output varies by transition type: + +- **Non-merged transitions** — advisory suggestion: + ``` + devpace:sync-push CR-003 state transition: created→developing, linked to github#42. + Consider running /pace-sync push to sync status. + ``` +- **Merged transition** — directive language (§11 step 7 safety net): + ``` + devpace:sync-push CR-003 state transition: in_review→merged, linked to github#42. + Auto-execute: /pace-sync push CR-003 (§11 step 7 — close Issue + done label + completion summary) + ``` + +**post-cr-update.mjs** — Detects merged state and outputs the full 7-step post-merge pipeline (§11 aligned). Step 7 (external sync push) is conditionally included only when `sync-mapping.md` exists and the CR has an external link. + +Both hooks never block workflow (always exit 0, async execution). + +## Roadmap + +| Phase | Features | Status | +|-------|----------|--------| +| Phase 18 (v1.5.0) | Semantic MVP + GitHub (`setup`/`link`/`push`/`unlink`/`create`/`status` + `--dry-run` + merged auto-push) | ✅ Current | +| Phase 19 | Smart push + Issue lifecycle + Gate sync + Multi-platform preview (Linear) | Planned | +| Phase 20 | Polling inbound + AI conflict resolution + Multi-platform full support | Planned | + +## Related Resources + +- [User Guide — /pace-sync section](../user-guide.md) — Quick reference +- [Design Document §19](../design/design.md) — Architecture decisions +- [sync-mapping-format.md](../../knowledge/_schema/sync-mapping-format.md) — Configuration schema +- [sync-procedures.md](../../skills/pace-sync/sync-procedures.md) — Platform-agnostic operation orchestration +- [sync-adapter-github.md](../../skills/pace-sync/sync-adapter-github.md) — GitHub adapter (gh CLI commands) +- [devpace-rules.md §16](../../rules/devpace-rules.md) — Runtime behavior rules diff --git a/docs/features/pace-sync_zh.md b/docs/features/pace-sync_zh.md new file mode 100644 index 0000000..dcfa2e3 --- /dev/null +++ b/docs/features/pace-sync_zh.md @@ -0,0 +1,273 @@ +# 外部工具同步（`/pace-sync`） + +devpace 是一个封闭系统——CR 状态完全存储在 `.devpace/` 内部。`/pace-sync` 通过**语义级同步**将 devpace 与 GitHub Issues 桥接：不是机械地将字段 A 映射到字段 B，而是 Claude 理解"这个变更请求正在被实现"后生成对应的外部操作。v1.5.0 作为 **push-only MVP** 发布；双向同步计划在 Phase 20 实现。 + +## 前置条件 + +| 条件 | 用途 | 是否必须 | +|------|------|:--------:| +| `gh` CLI | GitHub API 操作（标签、评论、Issue 状态） | 推荐 | +| `git remote` 已配置 | setup 时自动检测仓库 owner/name | 是 | +| `.devpace/` 已初始化 | 核心 devpace 项目结构 | 是 | + +> **优雅降级**：如果 `gh` CLI 未安装，`setup` 仍会生成配置文件（标注"未验证"）。`push` 和 `status` 需要 `gh` 才能运行。 + +## 快速上手 + +``` +1. /pace-sync setup → 检测 git remote → 生成 sync-mapping.md +2. /pace-sync link CR-003 #42 → 关联 CR-003 与 GitHub Issue #42 +3. /pace-sync push → 推送状态 → Issue #42 标签更新 +``` + +配置完成后，sync-push advisory hook 会在 CR 状态变更后自动提醒你推送。 + +## 命令参考 + +### `setup` + +引导式配置向导。 + +**语法**：`/pace-sync setup` + +检测 `git remote`，验证 `gh` CLI 连接，生成 `.devpace/integrations/sync-mapping.md`（按 [sync-mapping-format.md](../../knowledge/_schema/sync-mapping-format.md) Schema）。详细步骤见 [sync-procedures.md §2](../../skills/pace-sync/sync-procedures.md)。 + +**输出示例**： +``` +同步配置完成： +- 平台：GitHub (myorg/myrepo) +- 同步模式：push +- 连接状态：✅ 已验证 +下一步：用 /pace-sync link CR-xxx #Issue编号 关联变更请求 +``` + +**降级**：`gh` 不可用时仍创建配置文件，标注"连接未验证"。 + +### `link` + +关联 CR 与外部实体。 + +**语法**：`/pace-sync link <#外部ID>`（如 `link CR-003 #42`） + +验证 CR 和外部实体均存在后，将关联写入 CR 文件和 sync-mapping.md。详细步骤见 [sync-procedures.md §3](../../skills/pace-sync/sync-procedures.md)。 + +**错误处理**：CR 不存在、外部实体不存在 → 提示用户。CR 已有关联 → 确认后覆盖。 + +### `push` + +推送 devpace 状态到外部工具。 + +**语法**：`/pace-sync push [CR-ID] [--dry-run]` + +推送一个或所有已关联 CR 的状态到外部平台。使用 `--dry-run` 可预览操作而不实际执行。比较本地与外部状态，仅在不一致时更新。详细步骤见 [sync-procedures.md §4](../../skills/pace-sync/sync-procedures.md)。 + +**输出示例**： +``` +| CR | 状态 | 外部操作 | 结果 | +|--------|------------|----------------------|------| +| CR-003 | developing | 添加标签 in-progress | ✅ | +| CR-005 | merged | 关闭 Issue #18 + done | ✅ | +``` + +### `status` + +查看所有已关联 CR 的同步状态。 + +**语法**：`/pace-sync status` + +读取所有关联记录，比较 devpace 与外部状态，输出一致性表。详细步骤见 [sync-procedures.md §5](../../skills/pace-sync/sync-procedures.md)。 + +**输出示例**： +``` +| CR | 外部链接 | devpace 状态 | 外部状态 | 一致性 | 最后同步 | +|--------|---------|-------------|--------------|----------|------------| +| CR-003 | #42 | developing | in-progress | ✅ | 02-25 10:30 | +| CR-005 | #18 | merged | open | ❌ 需推送 | 02-24 15:00 | +``` + +## 状态映射 + +devpace CR 状态与 GitHub 标签对应（如 `developing` → `in-progress`，`merged` → 关闭 Issue + `done`）。完整映射表定义于 [sync-mapping-format.md](../../knowledge/_schema/sync-mapping-format.md)（Schema 权威源）和 [sync-adapter-github.md](../../skills/pace-sync/sync-adapter-github.md)（GitHub 特有操作）。 + +实际生效的同步方向取"平台同步模式"与"状态同步方向"的交集。当同步模式为 `push` 时，即使状态映射标记为 ↔，实际也只执行 → 方向。 + +## 使用场景 + +### 场景 1：首次配置 + +你有一个已有的 devpace 项目，想要开始与 GitHub Issues 同步。 + +``` +你： /pace-sync setup +Claude: 检测到仓库：myorg/my-project + 同步模式：push（MVP 推荐） + 冲突策略：ask-user + 是否验证连接？[Y/n] + +你： Y +Claude: ✅ 连接已验证 + 配置已写入 .devpace/integrations/sync-mapping.md + + 下一步：/pace-sync link CR-xxx #Issue编号 +``` + +### 场景 2：日常开发推送 + +`/pace-dev` 将 CR-003 从 `created` 转换为 `developing` 后，sync-push hook 检测到实际状态转换并提醒你： + +``` +Hook: devpace:sync-push CR-003 state transition: created→developing, linked to github#42. + Consider running /pace-sync push to sync status. + +你： /pace-sync push CR-003 +Claude: | CR | 状态 | 操作 | 结果 | + |--------|------------|---------------------|------| + | CR-003 | developing | 添加标签 in-progress | ✅ | +``` + +### 场景 3：一致性检查 + +发布前验证所有 CR 同步状态： + +``` +你： /pace-sync status +Claude: | CR | 外部链接 | devpace | 外部状态 | 一致 | 最后同步 | + |--------|---------|------------|---------------|------|------------| + | CR-003 | #42 | merged | done (closed) | ✅ | 02-25 14:00 | + | CR-005 | #18 | developing | backlog | ❌ | 02-24 15:00 | + + 1 个 CR 未同步。运行 /pace-sync push 更新。 +``` + +## 配置参考 + +同步配置存储在 `.devpace/integrations/sync-mapping.md`，遵循 [sync-mapping-format.md](../../knowledge/_schema/sync-mapping-format.md) Schema。 + +### 平台 + +```markdown +## 平台 + +- **类型**：github +- **连接**：myorg/myrepo +- **同步模式**：push +- **冲突策略**：ask-user +``` + +### 状态映射表 + +可按项目自定义。默认映射可修改为自定义标签名： + +```markdown +| devpace 状态 | 外部状态 | 方向 | 备注 | +|-------------|------------------------|------|---------------| +| created | open + my-custom-label | ↔ | 自定义标签名 | +``` + +[sync-mapping-format.md](../../knowledge/_schema/sync-mapping-format.md) Schema 定义了所有配置 section：平台字段、状态映射、实体映射、Gate 结果同步和关联记录。 + +## 与其他命令的集成 + +`/pace-dev` 和 `/pace-change` 在 CR 状态变更后触发 sync-push advisory hook 提醒推送。`/pace-status` 在 CR 信息旁展示同步状态。未来集成包括 `/pace-release` 和 `/pace-review`（Phase 19）。完整集成矩阵见 [sync-procedures.md §7](../../skills/pace-sync/sync-procedures.md)。 + +## 架构说明（开发者向） + +### 语义桥接概念 + +传统集成做的是机械的"字段 A → 字段 B"映射。devpace 采取了根本不同的方法： + +- **语义理解**：CR `developing` 不是简单映射为 GitHub `in-progress` 标签，而是 Claude 理解"这个变更请求正在被实现"后生成对应操作。 +- **上下文动作**：外部 PR merge 不只是触发状态变化——Claude 理解"代码已合入，需要推进质量门检查"。 +- **智能冲突解决**：冲突不是用"谁赢"的规则解决，而是 Claude 分析双方上下文后给出建议。 + +### 分层架构 + +``` +┌──────────────────────────────────┐ +│ pace-sync Skill 层 │ +│ setup / link / push / status │ +├──────────────────────────────────┤ +│ 语义桥接层（核心价值） │ +│ 意图映射 + 冲突检测 + 适配器路由 │ +├──────────────────────────────────┤ +│ 现有 MCP/CLI（不自建） │ +│ gh CLI / Linear MCP / Jira MCP │ +├──────────────────────────────────┤ +│ 配置层 │ +│ sync-mapping.md + config.md │ +└──────────────────────────────────┘ +``` + +**关键决策**：devpace **不**自建 MCP Server——GitHub、Linear、Jira、GitLab 都有成熟的现有工具。devpace 专注于语义编排层。 + +### 适配器路由 + +| 操作 | GitHub (gh CLI) | Linear (MCP) | Jira (MCP/CLI) | +|------|----------------|--------------|----------------| +| 创建工作项 | `gh issue create` | `mcp__linear__create_issue` | Phase 19+ | +| 更新状态 | `gh issue edit --add-label` | `mcp__linear__update_issue` | Phase 19+ | +| 添加评论 | `gh issue comment` | `mcp__linear__create_comment` | Phase 19+ | +| 获取状态 | `gh issue view --json` | `mcp__linear__get_issue` | Phase 19+ | + +MVP 默认使用 GitHub（通过 gh CLI，零额外依赖）。 + +### 扩展点 + +添加新平台适配器的步骤： + +1. 在 sync-mapping-format.md 的 `类型` 字段添加新平台值 +2. 在 `sync-procedures.md §1` 添加工具路由 section +3. 添加该平台的默认状态映射 +4. 无需修改 Skill——适配器路由在 procedures 层 + +## 降级行为与故障排除 + +### 降级行为 + +所有子命令均优雅降级：缺少 sync-mapping.md 时引导运行 `setup`，`gh` CLI 不可用时允许创建配置但阻断 push/status，缺少关联时静默跳过。完整降级矩阵定义于 [sync-mapping-format.md](../../knowledge/_schema/sync-mapping-format.md)。 + +### 常见问题 + +| 问题 | 原因 | 解决方案 | +|------|------|---------| +| `gh auth` 错误 | 未登录 | 运行 `gh auth login` | +| 标签不存在 | 自定义标签未创建 | 首次 push 时自动创建 | +| 仓库错误 | 多个 remote | 重新运行 `setup` 选择正确 remote | +| 同步状态过时 | 手动修改了外部状态 | 运行 `status` 检测漂移，再 `push` | + +### 辅助 Hook（双层保障） + +两个 PostToolUse Hook 协作确保 CR 状态转换时的外部同步： + +**sync-push.mjs** — 基于文件缓存（`.devpace/.sync-state-cache`）的状态变化检测。仅在**实际状态转换**时触发，普通编辑静默忽略（消除噪音）。输出按转换类型分级： + +- **非 merged 转换** — 建议性提醒： + ``` + devpace:sync-push CR-003 state transition: created→developing, linked to github#42. + Consider running /pace-sync push to sync status. + ``` +- **merged 转换** — 指令性语言（§11 第 7 步安全网）： + ``` + devpace:sync-push CR-003 state transition: in_review→merged, linked to github#42. + Auto-execute: /pace-sync push CR-003 (§11 step 7 — close Issue + done label + completion summary) + ``` + +**post-cr-update.mjs** — 检测 merged 状态后输出完整 7 步 post-merge 管道（对齐 §11）。第 7 步（外部同步推送）仅在 `sync-mapping.md` 存在且 CR 有外部关联时才包含。 + +两个 Hook 均不阻断工作流（始终 exit 0，异步执行）。 + +## 路线图 + +| 阶段 | 功能 | 状态 | +|------|------|------| +| Phase 18 (v1.5.0) | 手动推送 + GitHub MVP（`setup`/`link`/`push`/`status`） | ✅ 当前 | +| Phase 19 | 状态变更自动推送 + 多平台（Linear、Jira）+ `pull` 子命令 | 计划中 | +| Phase 20 | 双向同步 + AI 冲突解决 + `sync`/`resolve` 子命令 | 计划中 | + +## 相关资源 + +- [用户指南 — /pace-sync 章节](../user-guide_zh.md) — 快速参考 +- [设计文档 §19](../design/design.md) — 架构决策 +- [sync-mapping-format.md](../../knowledge/_schema/sync-mapping-format.md) — 配置格式 Schema +- [sync-procedures.md](../../skills/pace-sync/sync-procedures.md) — 详细操作规程 +- [devpace-rules.md §16](../../rules/devpace-rules.md) — 运行时行为规则 diff --git a/docs/planning/progress.md b/docs/planning/progress.md index efd24d6..187695c 100644 --- a/docs/planning/progress.md +++ b/docs/planning/progress.md @@ -18,15 +18,15 @@ | 维度 | 值 | |------|---| -| 版本 | **v1.4.0** Risk Fabric 风险织网 | -| 当前阶段 | **Phase 1-17 全部完成 ✅** | -| 当前里程碑 | 全部 ✅（M1.1-M17.1） | -| 任务进度 | **105/105 ✅ 全部完成** | -| 场景覆盖 | 31/31 用户场景 · 60/60 功能需求 | +| 版本 | **v1.5.0** External Sync（进行中） | +| 当前阶段 | **Phase 18 ✅ 完成**（M18.1 ✅ M18.2 ✅ M18.3 ✅） | +| 当前里程碑 | Phase 18 全部完成，Phase 19 待开始 | +| 任务进度 | **107/111**（T107 ✅，T108-T111 待做） | +| 场景覆盖 | 34/34 用户场景 · 68/68 功能需求 | | 基础设施 | LICENSE ✅ · README ✅ · CONTRIBUTING ✅ · CHANGELOG ✅ · 用户指南 ✅ · 示例项目 ✅ · Hook Node.js ✅ · Agent 角色 ✅ · Model Tiering ✅ · CSO 审计 ✅ · 迁移验证 ✅ · Agent Memory ✅ · Async Hook ✅ · prompt Hook ✅ · Output Style ✅ | | 阻塞项 | 无 | -| 下一步 | 1) 聚合平台注册（手动，见遗留事项） 2) rules 最后 7 行瘦身至 400（收益递减，可选） 3) Hook 体系进一步优化（Stop/SessionEnd 职责精化） | -| 最后更新 | 2026-02-25 | +| 下一步 | 1) v1.5.0 版本发布 2) Phase 19 智能推送 3) 聚合平台注册 | +| 最后更新 | 2026-02-26 | ## 当前任务 @@ -160,6 +160,13 @@ | T104 | GitHub Actions CI 完善 | -- | OBJ-3 | ✅ 完成 | validate.yml 重构为 2 个独立 job：lint（Markdown lint + layer separation，无需 Python）和 test（pytest，Python 3.9/3.12 矩阵）。消除 markdownlint 在矩阵中重复执行。layer-check 错误用 ::error:: annotation。204 测试通过 | | | **Phase 17 — Risk Fabric 风险织网** | | | | | | T105 | Risk Fabric 核心实现 | M17.1 | OBJ-1, OBJ-3 | ✅ 完成 | 新增 /pace-guard Skill（5 子命令：scan/monitor/trends/report/resolve）+ risk-format.md Schema + guard-procedures.md 执行规程。CR Schema 扩展（风险预评估+运行时风险可选 section）。嵌入集成：dev-procedures 意图检查点风险预扫描 + pulse 第 8 信号"风险积压" + retro 风险趋势段。Rules §10 风险感知 + 分级自主响应矩阵。213 测试通过 | +| | **Phase 18 — 外部同步 MVP** | | | | | +| T106 | pace-sync 产品优化 16 项（Wave 1-4） | M18.2 | OBJ-1, OBJ-12, F11.1-F11.14 | ✅ 完成 | 13 文件 310 行增量。Wave 1：C1 标签预创建 + A1 语义 Comment + B1 unlink + B2 dry-run。Wave 2：D1 status 同步摘要 + D3 change 同步提醒 + B3 create 子命令 + B4 Gate 同步规程。Wave 3：D4 教学触发 + D5 pulse 同步滞后信号 + C2 限流保护 + C3 Issue 状态检查 + A2 副产物非前置三阶段。Wave 4：A3 入站轮询架构设计。Roadmap Phase 18/19/20 修订 + design §19 更新 + 附录 B 架构图追加。223 pytest + markdownlint + 层隔离全通过 | +| T107 | M18.3 Hook + Rules + 语义同步集成 | M18.3 | OBJ-1, OBJ-12, F11.8, F11.13 | ✅ 完成 | 7 文件变更：utils.mjs 缓存工具（+readSyncStateCache/updateSyncStateCache）+ sync-push.mjs 重写（缓存比对+merged 指令分级）+ post-cr-update.mjs 7 步管道对齐 §11（+条件第 7 步外部同步）+ test_hooks.py（sync-push 注册+TC-HK-16）+ rules §16 三处文案精炼 + feature docs 双层保障 section。224 pytest + markdownlint + 层隔离 + plugin 加载全通过 | +| T108 | Phase 19 M19.1 智能推送 + Gate 同步 | M19.1 | OBJ-1, OBJ-12, F11.12 | 待做 | auto-create+auto-link + Gate Comment/Label + 教学+pulse | +| T109 | Phase 19 M19.2 Issue 生命周期 | M19.2 | OBJ-12, F11.11 | 待做 | create 端到端 + PR 关联 + 治理集成 | +| T110 | Phase 19 M19.3 多平台预研 | M19.3 | OBJ-17 | 待做 | Linear 原型适配器 | +| T111 | Phase 20 M20.1 轮询式入站感知 | M20.1 | OBJ-1, F11.14 | 待做 | /pace-sync pull + 会话开始外部变更检查 | ## 关键决策 @@ -178,6 +185,11 @@ | 日期 | 变更 | 原因 | |------|------|------| +| 2026-02-26 | 会话结束 | -- | +| 2026-02-26 | T107 M18.3 Hook+Rules+语义同步集成：utils.mjs 缓存工具（readSyncStateCache/updateSyncStateCache，`.devpace/.sync-state-cache` 纯文本格式）+ sync-push.mjs 重写（缓存比对消除噪音+merged 指令 vs 普通建议分级，F11.8）+ post-cr-update.mjs 7 步管道对齐 §11（+条件第 7 步外部同步检测 sync-mapping+外部关联，F11.13）+ test_hooks.py sync-push 注册+TC-HK-16 async 验证 + rules §16 三处文案精炼（缓存比对说明+双层保障+协调更新）+ feature docs 双层保障 section。M18.3 里程碑完成，Phase 18 全部关闭。224 pytest + markdownlint + 层隔离 + plugin 加载全通过 | M18.3 Hook+Rules 集成——状态变化检测+管道对齐+双层保障 | +| 2026-02-26 | pace-sync adapter pattern 重构（23a525a + 4cb9e2f）：sync-procedures.md 拆分为平台无关规程 + sync-adapter-github.md GitHub 适配器。design docs + feature docs 对齐更新 | 架构优化——OCP 原则，新增平台零修改 procedures | +| 2026-02-26 | /pace-init 综合优化 14 项（OPT-1~8 + NEW-1~6）：SKILL.md 重写（生命周期感知初始化 3 阶段 + --verify/--reset/--dry-run/--export-template 4 新子命令 + --from 增强目录+多文件+API 解析 + full 分阶段引导 + CLAUDE.md 智能合并 + 情境化引导 + 自动校验）+ init-procedures.md 重写（信号检测+阶段判定算法 + 阶段 A/B/C 策略 + CLAUDE.md devpace-start/end 标记幂等注入 + 工具链精准检测 Node.js/Python/Go/Rust 4 技术栈 + v0.1 迁移代码清理→v1.5.0 迁移框架 + context.md 阈值 3→1 + 健康检查/重置/dry-run/模板导出/Monorepo 感知 6 规程）+ templates/claude-md-devpace.md 添加标记。223 pytest + markdownlint + 层隔离 + plugin 加载全通过 | pace-init 产品优化分析方案实施 | +| 2026-02-25 | T106 pace-sync 产品优化 16 项（4 波次 8 并行 Agent 执行）：Wave 1 sync-procedures 核心增强（C1 标签预创建 + A1 语义 Comment + B1 unlink + B2 dry-run）+ D2 rules §11 第 7 步外部同步。Wave 2 集成深化（D1 status 同步摘要 + D3 change 同步提醒 + B3 create 子命令 + B4 Gate 同步规程）。Wave 3 质量体验（D4 教学触发 + D5 pulse 信号 + C2 限流 + C3 状态检查 + A2 副产物非前置三阶段）。Wave 4 设计（A3 入站轮询架构）。Roadmap Phase 18/19/20 修订 + design §19 事件模型+入站约束+附录 B + requirements F11.9-F11.14 + feature doc 同步。13 文件 310 行增量。223 pytest + markdownlint 全通过 | pace-sync 产品优化分析方案实施 | | 2026-02-25 | 会话结束 | -- | | 2026-02-25 | rules 二次瘦身 432→407 行（§6 会话结束+§8 溯源标记+§2 关注点引导+§13.5 透明模板 4 处压缩）+ TC-CR-08 裸文件名检测测试 + session-stop.sh 轻量化（移除 state.md 条件，职责委托 SessionEnd）+ user-guide.md 新增 /pace-guard 章节（子命令表+风险等级+自动触发+降级模式）。214 测试通过 | 瘦身收尾 + 回归防护 + v1.4.0 文档补齐 | | 2026-02-25 | 产品层 Plugin 机制与组件优化 10 项（P0×3+P1×2+P2×5）：P0 rules 程序性下沉（§2/§4/§11/§12/§14 压缩至 procedures）+ §0 速查卡片 56→33 行 + 铁律 IR-1~5 集中定义去重。P1 cr-reference.md 合并入 cr-format.md（消除字段权威歧义）+ checks-format 教学内容抽离至 checks-guide.md。P2 SessionEnd hook + pace-analyst AskUserQuestion + pace-dev 引用明确化 + pulse-counter timeout 3→5s + state-format 版本历史压缩。design.md 附录 B 同步更新（Schema 13→12、Knowledge 4→5、checks-guide 边）。devpace-rules.md 496→432 行（-13%）。213 测试通过 | SSOT 加强 + token 瘦身 + 维护成本降低 | @@ -249,33 +261,33 @@ > 保留最近 5 条，超出时删除最旧记录。 -### 2026-02-25 — 产品层优化 + 瘦身收尾 + /pace-guard 文档 +### 2026-02-26 — T107 M18.3 Hook+Rules+语义同步集成 -- **完成**：① 10 项 Plugin 机制优化（3 Agent 并行，rules 496→432 行，cr-reference 合并删除，checks-guide 新建，SessionEnd hook，design 附录 B 同步）② rules 二次瘦身 432→407 行（§6/§8/§2/§13.5 四处压缩）③ TC-CR-08 裸文件名检测测试 ④ session-stop.sh 轻量化 ⑤ user-guide.md /pace-guard 章节。214 测试通过 -- **决策**：铁律 IR-1~5 集中定义于 §0（SSOT），§2/§10 改为编号引用；rules/ 中 `详见` 引用强制路径前缀 +- **完成**：7 文件变更。utils.mjs +缓存工具（readSyncStateCache/updateSyncStateCache）+ sync-push.mjs 重写（缓存比对+merged 指令分级）+ post-cr-update.mjs 7 步管道对齐 §11（+条件第 7 步）+ test_hooks.py（sync-push 注册+TC-HK-16）+ rules §16 三处文案 + feature docs 双层保障。M18.3 完成，Phase 18 全部关闭 +- **决策**：状态缓存采用纯文本 `.devpace/.sync-state-cache`（不入 git），与 pulse-counter 的 `.pulse-count` 先例一致 - **未完成**：无 -- **下次建议**：1) 聚合平台注册 2) rules 最后 7 行瘦身（可选） 3) Hook 体系精化 +- **下次建议**：1) v1.5.0 版本发布 2) Phase 19 智能推送 3) 聚合平台注册 -### 2026-02-25 — 产品层 Token 效率优化 +### 2026-02-26 — /pace-init 综合优化 14 项 -- **完成**：7 项优化（OPT-1~7），4 Agent 并行执行。rules 常驻 511→476 行（-35 行/~2-3K tokens/会话）、/pace-test 子命令加载减少 ~300-525 行/次、cr-format -21 行、pace-feedback SKILL.md 98→48 行。net -698 行（119 ins / 817 del）。206 测试 + markdownlint + 层隔离 + plugin 加载全部通过 -- **决策**：Schema 映射表从 rules 常驻移除（Claude 直接查 `_schema/` 目录或由 Skill procedures 指定） -- **未完成**：git commit 待执行 -- **下次建议**：1) git commit 2) 手动抽检 /pace-test strategy 和 coverage 路由 3) 聚合平台注册 +- **完成**：14 项优化实施（OPT-1~8 优化 + NEW-1~6 新增）。3 文件重写：SKILL.md（生命周期感知 3 阶段 + 4 新子命令 + --from 增强 + full 分阶段 + CLAUDE.md 合并 + 引导优化）+ init-procedures.md（信号检测算法 + 阶段策略 + 工具链精准检测 4 技术栈 + 迁移框架 + context.md 阈值调优 + 6 新规程）+ claude-md-devpace.md 模板标记。223 pytest + markdownlint + 层隔离 + plugin 加载全通过 +- **决策**：生命周期检测采用信号组合判定（git commit/tags/部署配置/源文件数），不暴露阶段标签给用户 +- **未完成**：无 +- **下次建议**：1) M18.3 Hook+语义集成 2) 版本发布 3) Phase 19 -### 2026-02-24 — 生态调研 + 全任务完成 + v1.3.0 发布 + P1-7/P2-4 增强 +### 2026-02-25 — pace-sync 产品优化 16 项（T106） -- **完成**：生态调研（4 Agent Teams 并行，7 盲区）→ P0×5 + P1×2 落地（T99-T104）→ Phase 16 全部完成（T95-T97）→ v1.3.0 发布 → roadmap Phase 16 关闭 → P1-7 Graceful Degradation（§13.5 inline 回退）+ P2-4 Human Transparency（变更摘要模板 + 不透明禁令）。**104/104 全部完成，Phase 1-16 关闭** -- **决策**：无新架构决策 -- **未完成**：聚合平台注册需手动操作（见遗留事项） -- **下次建议**：1) 聚合平台手动注册 2) 剩余 P1/P2 选做（P1-3 Confidence Scoring 等） +- **完成**：16 项优化 4 波次实施（8 并行 Agent）。Wave 1：C1 标签预创建 + A1 语义 Comment + B1 unlink + B2 dry-run + D2 §11 第 7 步。Wave 2：D1 status 同步 + D3 change 同步 + B3 create + B4 Gate 同步。Wave 3：D4 教学 + D5 pulse 信号 + C2 限流 + C3 状态检查 + A2 副产物非前置。Wave 4：A3 入站架构设计。13 文件 310 行增量。Roadmap Phase 18/19/20 修订 + design §19 + 附录 B + requirements F11 + feature doc 同步。223 pytest + markdownlint 全通过 +- **决策**：入站架构采用轮询模式（CLI Plugin 无 webhook），pull 从 Phase 19 移到 Phase 20 +- **未完成**：无 +- **下次建议**：1) M18.3 Hook+语义集成 2) 版本发布 3) Phase 19 -### 2026-02-25 — Risk Fabric v1.4.0 完整交付（T105） +### 2026-02-25 — 产品层优化 + 瘦身收尾 + /pace-guard 文档 -- **完成**：brainstorming（4 轮问答）→ 设计文档 → 12 Task subagent-driven 实现 → v1.4.0 版本发布 → 上游级联（design §18 + requirements S31/F10 + roadmap Phase 17）→ 真实项目验证通过。**105/105 全部完成，Phase 1-17 关闭** -- **决策**：D8 风险织网采用"专属入口 + 嵌入式智能"双路径，风险状态机独立于 CR 状态机 +- **完成**：① 10 项 Plugin 机制优化（3 Agent 并行，rules 496→432 行，cr-reference 合并删除，checks-guide 新建，SessionEnd hook，design 附录 B 同步）② rules 二次瘦身 432→407 行（§6/§8/§2/§13.5 四处压缩）③ TC-CR-08 裸文件名检测测试 ④ session-stop.sh 轻量化 ⑤ user-guide.md /pace-guard 章节。214 测试通过 +- **决策**：铁律 IR-1~5 集中定义于 §0（SSOT），§2/§10 改为编号引用；rules/ 中 `详见` 引用强制路径前缀 - **未完成**：无 -- **下次建议**：1) 聚合平台注册 2) 用户指南追加 /pace-guard 章节 3) 新方向探索 +- **下次建议**：1) 聚合平台注册 2) rules 最后 7 行瘦身（可选） 3) Hook 体系精化 ## 遗留事项 diff --git a/docs/planning/requirements.md b/docs/planning/requirements.md index 7f119da..3c2deac 100644 --- a/docs/planning/requirements.md +++ b/docs/planning/requirements.md @@ -494,6 +494,61 @@ | F7.5 | 纠正即学习（§12.5 反应式调优） | S26 | P1 | | F7.6 | insights-format 偏好条目类型 | S26 | P1 | +### S32：首次配置同步 + +**前置**：项目已初始化（`.devpace/` 存在），已安装 `gh` CLI + +| 步骤 | 用户行为 | Claude 行为 | +|------|---------|-------------| +| 1 | "配置 GitHub 同步" 或 /pace-sync setup | 检测 git remote → 提取 owner/repo → 引导确认 | +| 2 | 确认仓库信息 | 生成 sync-mapping.md + 更新 config.md | +| 3 | — | 输出：同步已配置，可用 /pace-sync link 关联 CR | + +- [x] 验收：sync-mapping.md 生成且格式合规 + +### S33：CR 关联外部 Issue + +**前置**：sync-mapping.md 存在 + +| 步骤 | 用户行为 | Claude 行为 | +|------|---------|-------------| +| 1 | "/pace-sync link CR-003 #42" | 验证 CR 存在 + Issue 存在（gh issue view） | +| 2 | — | CR-003.md 写入外部关联 + sync-mapping.md 更新关联记录 | +| 3 | — | 输出：已关联，可用 /pace-sync push 推送状态 | + +- [x] 验收：CR 文件和 sync-mapping.md 关联记录一致 + +### S34：推送状态到外部 + +**前置**：CR 已关联外部 Issue + +| 步骤 | 用户行为 | Claude 行为 | +|------|---------|-------------| +| 1 | "/pace-sync push" 或 CR 状态变化后提醒 | 读取 CR 当前状态 + 查询映射表 | +| 2 | — | 通过 gh CLI 更新 Issue 标签/Comment | +| 3 | — | 输出：CR-003（developing）→ Issue #42 标签已更新 | + +- [x] 验收：外部 Issue 状态与 CR 状态一致 + +### F11：外部工具同步 + +| ID | 功能 | 对应场景 | 优先级 | +|----|------|---------|:------:| +| F11.1 | /pace-sync setup：引导式同步配置 | S32 | P1 | +| F11.2 | /pace-sync link：CR ↔ 外部实体关联 | S33 | P1 | +| F11.3 | /pace-sync push：推送 devpace 状态到外部 | S34 | P1 | +| F11.4 | /pace-sync status：同步状态查看 | S32-S34 | P1 | +| F11.5 | /pace-sync pull：拉取外部状态到 devpace | — | P2 | +| F11.6 | /pace-sync sync：双向同步 | — | P3 | +| F11.7 | /pace-sync resolve：AI 冲突解决 | — | P3 | +| F11.8 | sync-push Hook：CR 状态变化提醒推送 | S34 | P1 | +| F11.9 | /pace-sync unlink：解除 CR 外部关联 | S32-S34 | P1 | +| F11.10 | /pace-sync push --dry-run：预览同步操作 | S34 | P1 | +| F11.11 | /pace-sync create：从 CR 创建外部 Issue | S33 | P2 | +| F11.12 | Gate 结果自动推送 Comment + Label | S34 | P2 | +| F11.13 | merged 自动 push 闭环 | S34 | P1 | +| F11.14 | 轮询式入站感知（会话开始拉取外部变更） | — | P3 | + ## 非功能需求 | ID | 需求 | 标准 | diff --git a/docs/planning/roadmap.md b/docs/planning/roadmap.md index cda37aa..2adaaf1 100644 --- a/docs/planning/roadmap.md +++ b/docs/planning/roadmap.md @@ -36,6 +36,9 @@ | Phase 15 | 测试策略与验收验证 | /pace-test 三层测试管理（基础执行 + 策略管理 + AI 验收） | ✅ 完成 | | Phase 16 | 企业级扩展 | DORA 代理指标 + 跨项目经验复用 + CI/CD 自动感知 | ✅ 完成 | | Phase 17 | Risk Fabric 风险织网 | /pace-guard + risk-format + 嵌入集成 + 分级自主 | ✅ 完成 | +| Phase 18 | 外部同步 MVP | 手动同步 + GitHub MVP（pace-sync setup/link/push/status） | ✅ 完成 | +| Phase 19 | 自动推送与多平台 | 自动推送 + 治理集成 + Linear/Jira 扩展 | 待开始 | +| Phase 20 | 双向同步与 AI 冲突 | 入站事件 + 冲突检测 + AI 解决 | 待开始 | --- @@ -522,12 +525,66 @@ --- +## Phase 18：外部同步 MVP + +**目标**：pace-sync Skill 核心子命令 + GitHub（gh CLI）+ 手动推送 + 语义 Comment + MVP 闭环。让用户能通过 `/pace-sync` 将 CR 状态推送到 GitHub Issue，merged 时自动同步关闭。 + +**对应 OBJ**：OBJ-1, OBJ-12 + +### 里程碑 + +| # | 里程碑 | 状态 | 产出 | +|---|--------|------|------| +| M18.1 | Schema + 配置基础 | ✅ 完成 | sync-mapping-format.md + integrations/cr Schema 扩展 | +| M18.2 | Skill 基础 + 运行时修复 | ✅ 完成 | SKILL.md + sync-procedures.md（setup/link/push/status）+ 标签预创建 + unlink + dry-run | +| M18.3 | Hook + Rules + 语义同步 | ✅ 完成 | sync-push.mjs 缓存比对 + post-cr-update.mjs 7 步管道 + §16 精炼 + feature docs 双层保障 | + +### 任务定义 + +> 实时状态见 [progress.md](progress.md) "当前任务"表。 + +--- + +## Phase 19：智能推送与 Issue 生命周期 + +**目标**：自动推送（副产物非前置）+ Issue 创建能力 + Gate 结果同步 + 教学增强 + 健康信号。 + +**对应 OBJ**：OBJ-1, OBJ-12, OBJ-17 + +### 里程碑 + +| # | 里程碑 | 状态 | 产出 | +|---|--------|------|------| +| M19.1 | 智能推送 + Gate 同步 | 待开始 | auto-create + auto-link + Gate Comment/Label + 教学触发 + pulse 信号 | +| M19.2 | Issue 生命周期 | 待开始 | create 子命令 + PR 关联能力 + 治理集成 | +| M19.3 | 多平台预研 | 待开始 | Linear 原型适配器 | + +--- + +## Phase 20：轮询入站与冲突解决 + +**目标**：轮询式入站感知（CLI Plugin 无 webhook 约束）+ 冲突检测与 AI 解决 + 多平台正式支持。 + +**对应 OBJ**：OBJ-1, OBJ-12, OBJ-17 + +### 里程碑 + +| # | 里程碑 | 状态 | 产出 | +|---|--------|------|------| +| M20.1 | 轮询式入站感知 | 待开始 | /pace-sync pull + 会话开始检查外部变更 | +| M20.2 | AI 冲突解决 | 待开始 | /pace-sync resolve + 语义冲突检测 | +| M20.3 | 多平台正式 + CI 回流 | 待开始 | Linear/Jira 正式适配器 + CI 结果回流 | + +--- + ## 变更记录 > 操作级变更记录已移至 [progress.md](progress.md)。此处仅保留战略级变更。 | 日期 | 变更 | 原因 | |------|------|------| +| 2026-02-25 | Phase 18 里程碑扩展（M18.2+M18.3 新增 C1/B1/B2/A1/D2/D1 内容）；Phase 19 重组为智能推送+Issue 生命周期+多平台预研；Phase 20 重组为轮询入站+冲突解决+多平台正式（pull 从 Phase 19 移入，webhook 约束明确） | pace-sync 产品优化分析 | +| 2026-02-25 | 新增 Phase 18-20：外部工具同步（M18.1-M18.3, M19.1-M19.3, M20.1-M20.3） | v1.5.0 External Tool Semantic Bridge，语义级双向桥接 | | 2026-02-25 | 新增 Phase 17：Risk Fabric 风险织网（M17.1） | OBJ-1/OBJ-3 能力延伸，独立风险实体 + 全生命周期风险管理 | | 2026-02-23 | 新增 Phase 16：企业级扩展（M16.1-M16.3） | vision.md 定位调整（企业开发者 + Ops 分阶段覆盖），新增 OBJ-15/16/17 | | 2026-02-23 | 新增 Phase 15：测试策略与验收验证（M15.1-M15.3） | /pace-test BizDevOps 感知的测试策略命令，三层测试管理体系 | diff --git a/docs/user-guide.md b/docs/user-guide.md index 970aa50..345a8d5 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -16,6 +16,7 @@ For a quick overview, see [README.md](../README.md). For a hands-on walkthrough, - [Quality Gates](#quality-gates) - [Cross-Session Continuity](#cross-session-continuity) - [Project Files](#project-files) +- [Methodology Mapping](#methodology-mapping) - [Tips](#tips) - [FAQ](#faq) @@ -100,7 +101,7 @@ devpace uses a precise internal concept model, but everything in conversation is > **Core commands** (daily use): `/pace-init`, `/pace-dev`, `/pace-status`, `/pace-review`, `/pace-next` > **Advanced commands** (when needed): `/pace-change`, `/pace-plan`, `/pace-retro` -> **Specialized commands** (optional): `/pace-test`, `/pace-release`, `/pace-guard`, `/pace-feedback`, `/pace-role`, `/pace-theory`, `/pace-trace` +> **Specialized commands** (optional): `/pace-test`, `/pace-release`, `/pace-guard`, `/pace-sync`, `/pace-feedback`, `/pace-role`, `/pace-theory`, `/pace-trace` ### `/pace-init [name] [full]` @@ -464,6 +465,44 @@ You can pass Gate 2 without running accept — but changes with accept have stro --- +### `/pace-sync [subcommand] [args]` *(optional)* + +> Bridges devpace state with external project management tools (GitHub Issues). Push-only MVP in v1.5.0. + +**When to use**: You want to keep GitHub Issues in sync with devpace CR states. + +**Prerequisites**: `gh` CLI installed (recommended), `git remote` configured. + +**Subcommands**: + +| Subcommand | Arguments | Description | +|------------|-----------|-------------| +| `setup` | — | Guided sync configuration (detect remote → generate sync-mapping.md) | +| `link` | `CR-ID #ExternalID` | Associate CR with GitHub Issue | +| `push` | `[CR-ID]` | Push devpace state to external (specific CR or all linked) | +| `status` | — | View sync status and external links | + +No arguments defaults to `status`. + +**State Mapping** (devpace → GitHub labels): + +| devpace | GitHub label | Direction | +|---------|-------------|:---------:| +| `created` | `backlog` | ↔ | +| `developing` | `in-progress` | ↔ | +| `verifying` | `needs-review` | → | +| `in_review` | `awaiting-approval` | → | +| `merged` | close + `done` | ↔ | +| `paused` | `on-hold` | ↔ | + +**Quick start**: `setup` → `link CR-003 #42` → `push` + +**Degradation**: No `gh` CLI → setup still works (config marked unverified), push/status unavailable. No sync-mapping.md → guides to setup. Core devpace workflow unaffected. + +For detailed scenarios and developer guide, see [External Tool Sync](features/pace-sync.md). + +--- + ### `/pace-role [role]` *(optional)* > Switches Claude's output perspective. Default is Dev perspective when not switched. @@ -717,6 +756,46 @@ Metrics dashboard. Updated by `/pace-retro`. --- +## Methodology Mapping + +devpace is built on [BizDevOps methodology](https://en.wikipedia.org/wiki/BizDevOps) — the integration of Business, Development, and Operations into a unified value delivery chain. This section maps devpace features to the methodology's lifecycle stages. + +### Lifecycle Stages + +| Stage | What happens | Who leads | devpace feature | Feedback loop | +|-------|-------------|-----------|----------------|---------------| +| **Goal Setting** | Define business goals and success metrics | You | `/pace-init`, `project.md` | Business loop | +| **Planning** | Break goals into features, plan iterations | You + Claude | `/pace-plan`, `/pace-change` | Product loop | +| **Development** | Code, test, quality gates | Claude (you decide) | `/pace-dev`, `/pace-guard` | Technical loop | +| **Verification** | Quality checks, requirement consistency, human review | Auto + You | `/pace-review`, `/pace-test` | Technical loop | +| **Release** | Changelog, version, tag, deploy, verify | Claude (you confirm) | `/pace-release` | Operations loop | +| **Feedback** | Collect feedback, track defects, measure outcomes | You + Claude | `/pace-feedback`, `/pace-retro` | Business loop | + +### Feedback Loops + +devpace implements four continuous feedback loops: + +| Loop | Scope | Cycle | How devpace implements it | +|------|-------|-------|--------------------------| +| **Business** | Goals → Outcomes | Per project / quarter | MoS (Measures of Success) tracking in `project.md`, `/pace-retro` for goal attainment review | +| **Product** | Features → User value | Per iteration | `/pace-plan` for iteration planning, `/pace-retro` for delivery review, `/pace-change` for mid-iteration adjustment | +| **Technical** | Code → Quality | Per task | Auto quality gates (Gate 1/2/3), `/pace-test` for requirement-traced verification | +| **Operations** | Deploy → Stability | Per release | `/pace-release` for release orchestration, `/pace-feedback report` for production incident tracking | + +### Metrics Framework + +devpace collects metrics across three dimensions (auto-generated from work data, zero manual input): + +| Dimension | Metrics | devpace feature | +|-----------|---------|----------------| +| **Delivery (DORA proxies)** | Deploy frequency, Lead time, Change failure rate, MTTR | `/pace-retro` with Elite~Low benchmarks | +| **Quality** | Gate first-pass rate, Human rejection rate, Defect escape rate | Auto quality gates + `/pace-test` | +| **Value alignment** | Success metric (MoS) attainment, Value chain completeness, Delivery cycle time | `project.md` traceability + `/pace-retro` | + +> For the full theoretical background, run `/pace-theory` inside devpace. + +--- + ## Tips ### Let devpace Handle the Bookkeeping diff --git a/docs/user-guide_zh.md b/docs/user-guide_zh.md index cf5e4d5..1e036c8 100644 --- a/docs/user-guide_zh.md +++ b/docs/user-guide_zh.md @@ -14,6 +14,7 @@ - [质量门禁](#质量门禁) - [跨会话连续性](#跨会话连续性) - [项目文件](#项目文件) +- [方法论映射](#方法论映射) - [使用技巧](#使用技巧) - [常见问题](#常见问题) @@ -98,7 +99,7 @@ devpace 内部使用精确的概念模型，但对话中一切都是自然语言 > **核心命令**（日常使用）：`/pace-init`、`/pace-dev`、`/pace-status`、`/pace-review`、`/pace-next` > **进阶命令**（需要时用）：`/pace-change`、`/pace-plan`、`/pace-retro` -> **专项命令**（可选）：`/pace-test`、`/pace-release`、`/pace-guard`、`/pace-feedback`、`/pace-role`、`/pace-theory`、`/pace-trace` +> **专项命令**（可选）：`/pace-test`、`/pace-release`、`/pace-guard`、`/pace-sync`、`/pace-feedback`、`/pace-role`、`/pace-theory`、`/pace-trace` ### `/pace-init [name] [full]` @@ -462,6 +463,44 @@ Gate 2 检查"代码是否与计划一致"。accept 在此基础上提供更精 --- +### `/pace-sync [子命令] [参数]` *（可选）* + +> 将 devpace 状态与外部项目管理工具（GitHub Issues）桥接。v1.5.0 为 push-only MVP。 + +**何时使用**：你想让 GitHub Issues 与 devpace CR 状态保持同步。 + +**前置条件**：安装 `gh` CLI（推荐），配置 `git remote`。 + +**子命令**： + +| 子命令 | 参数 | 说明 | +|--------|------|------| +| `setup` | — | 引导式同步配置（检测 remote → 生成 sync-mapping.md） | +| `link` | `CR-ID #外部ID` | 关联 CR 与 GitHub Issue | +| `push` | `[CR-ID]` | 推送 devpace 状态到外部（指定 CR 或全部已关联） | +| `status` | — | 查看同步状态和外部链接 | + +无参数时默认 `status`。 + +**状态映射**（devpace → GitHub 标签）： + +| devpace 状态 | GitHub 标签 | 方向 | +|-------------|------------|:----:| +| `created` | `backlog` | ↔ | +| `developing` | `in-progress` | ↔ | +| `verifying` | `needs-review` | → | +| `in_review` | `awaiting-approval` | → | +| `merged` | 关闭 + `done` | ↔ | +| `paused` | `on-hold` | ↔ | + +**快速上手**：`setup` → `link CR-003 #42` → `push` + +**降级**：无 `gh` CLI → setup 仍可用（配置标注未验证），push/status 不可用。无 sync-mapping.md → 引导 setup。核心 devpace 流程不受影响。 + +详细场景和开发者指南见[外部工具同步](features/pace-sync_zh.md)。 + +--- + ### `/pace-role [role]` *（可选）* > 切换 Claude 的输出视角。不切换时默认 Dev 视角。 @@ -712,6 +751,46 @@ Release 级别的检查（依赖 `integrations/config.md` 配置）： --- +## 方法论映射 + +devpace 基于 [BizDevOps 方法论](https://en.wikipedia.org/wiki/BizDevOps)构建——将业务（Biz）、开发（Dev）和运营（Ops）整合为统一的价值交付链。本节展示 devpace 功能与方法论生命周期阶段的对应关系。 + +### 生命周期阶段 + +| 阶段 | 做什么 | 谁主导 | devpace 功能 | 反馈闭环 | +|------|--------|--------|-------------|---------| +| **目标设定** | 定义业务目标和成功指标 | 你 | `/pace-init`、`project.md` | 业务闭环 | +| **规划** | 将目标分解为功能、规划迭代 | 你 + Claude | `/pace-plan`、`/pace-change` | 产品闭环 | +| **开发** | 编码、测试、质量门禁 | Claude（你来决策） | `/pace-dev`、`/pace-guard` | 技术闭环 | +| **验证** | 质量检查、需求一致性、人类审批 | 自动 + 你 | `/pace-review`、`/pace-test` | 技术闭环 | +| **发布** | Changelog、版本、Tag、部署、验证 | Claude（你确认） | `/pace-release` | 运维闭环 | +| **反馈** | 收集反馈、追踪缺陷、衡量成果 | 你 + Claude | `/pace-feedback`、`/pace-retro` | 业务闭环 | + +### 反馈闭环 + +devpace 实现四个持续反馈闭环： + +| 闭环 | 范围 | 周期 | devpace 如何实现 | +|------|------|------|-----------------| +| **业务闭环** | 目标 → 成果 | 项目/季度级 | `project.md` 中的 MoS（成效指标）追踪，`/pace-retro` 目标达成回顾 | +| **产品闭环** | 功能 → 用户价值 | 迭代级 | `/pace-plan` 迭代规划，`/pace-retro` 交付回顾，`/pace-change` 迭代中调整 | +| **技术闭环** | 代码 → 质量 | 任务级 | 自动质量门禁（Gate 1/2/3），`/pace-test` 需求追溯验证 | +| **运维闭环** | 部署 → 稳定性 | 发布级 | `/pace-release` 发布编排，`/pace-feedback report` 生产事件追踪 | + +### 度量体系 + +devpace 从三个维度自动采集度量（从工作数据中自动生成，零手动填写）： + +| 维度 | 度量指标 | devpace 功能 | +|------|---------|-------------| +| **交付效能（DORA 代理值）** | 部署频率、前置时间、变更失败率、MTTR | `/pace-retro`，含 Elite~Low 基准分级 | +| **质量保障** | 门禁一次通过率、人类打回率、缺陷逃逸率 | 自动质量门禁 + `/pace-test` | +| **价值对齐** | 成效指标达成率、价值链完整率、交付周期 | `project.md` 追溯链 + `/pace-retro` | + +> 了解完整理论背景，请在 devpace 中运行 `/pace-theory`。 + +--- + ## 使用技巧 ### 让 devpace 处理记账工作 diff --git a/hooks/hooks.json b/hooks/hooks.json index 7627927..4f577dc 100644 --- a/hooks/hooks.json +++ b/hooks/hooks.json @@ -45,6 +45,13 @@ "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pulse-counter.mjs", "timeout": 5, "statusMessage": "devpace pulse counter" + }, + { + "type": "command", + "command": "${CLAUDE_PLUGIN_ROOT}/hooks/sync-push.mjs", + "timeout": 5, + "async": true, + "statusMessage": "devpace sync check" } ] } diff --git a/hooks/lib/utils.mjs b/hooks/lib/utils.mjs index 8940a15..9e90167 100644 --- a/hooks/lib/utils.mjs +++ b/hooks/lib/utils.mjs @@ -3,8 +3,9 @@ * Pure Node.js ESM — no npm dependencies. */ -import { readFileSync } from 'node:fs'; +import { readFileSync, writeFileSync, mkdirSync } from 'node:fs'; import { createInterface } from 'node:readline'; +import { dirname } from 'node:path'; /** * Read stdin and JSON.parse it. Returns {} on any failure. @@ -107,3 +108,47 @@ export function isStateChangeToApproved(content) { if (!content) return false; return /\*\*状态\*\*[：:]\s*approved/.test(content); } + +/** + * Read the sync state cache (.devpace/.sync-state-cache). + * Returns a Map. Returns empty Map on any failure. + * Cache format: plain text, one "CR-xxx=state" per line. + */ +export function readSyncStateCache(projectDir) { + const cache = new Map(); + try { + const cachePath = `${projectDir}/.devpace/.sync-state-cache`; + const content = readFileSync(cachePath, 'utf-8'); + for (const line of content.split('\n')) { + const trimmed = line.trim(); + if (!trimmed) continue; + const eqIdx = trimmed.indexOf('='); + if (eqIdx > 0) { + cache.set(trimmed.slice(0, eqIdx), trimmed.slice(eqIdx + 1)); + } + } + } catch { + // File doesn't exist or unreadable — return empty cache + } + return cache; +} + +/** + * Update a single entry in the sync state cache. + * Creates the cache file and .devpace/ directory if needed. + */ +export function updateSyncStateCache(projectDir, crName, newState) { + try { + const cachePath = `${projectDir}/.devpace/.sync-state-cache`; + const cache = readSyncStateCache(projectDir); + cache.set(crName, newState); + const lines = []; + for (const [name, state] of cache) { + lines.push(`${name}=${state}`); + } + mkdirSync(dirname(cachePath), { recursive: true }); + writeFileSync(cachePath, lines.join('\n') + '\n', 'utf-8'); + } catch { + // Cache write failure is non-critical — silent exit + } +} diff --git a/hooks/post-cr-update.mjs b/hooks/post-cr-update.mjs index a08fc75..209838b 100755 --- a/hooks/post-cr-update.mjs +++ b/hooks/post-cr-update.mjs @@ -3,13 +3,13 @@ * devpace PostToolUse hook — detect CR merged state and trigger knowledge pipeline * * Purpose: After a Write/Edit to a CR file, check if the CR transitioned to 'merged'. - * If so, output a reminder for Claude to trigger the post-merge pipeline: - * knowledge extraction (pace-learn) + incremental metrics update. + * If so, output a reminder for Claude to trigger the post-merge pipeline (§11 aligned): + * 7-step pipeline for merged CR processing, with conditional step 7 for external sync. * * This is an advisory hook (exit 0), not blocking. */ -import { existsSync } from 'node:fs'; +import { readFileSync, existsSync } from 'node:fs'; import { basename } from 'node:path'; import { readStdinJson, getProjectDir, extractFilePath, isCrFile, readCrState } from './lib/utils.mjs'; @@ -36,7 +36,32 @@ if (existsSync(filePath)) { if (currentState === 'merged') { const crName = basename(filePath, '.md'); - console.log(`devpace:post-merge ${crName} merged. Execute post-merge pipeline: 1) Run pace-learn for knowledge extraction 2) Update dashboard.md metrics incrementally 3) Check PF completion for release note 4) Update state.md and iterations/current.md`); + + // Build pipeline message — steps 1-6 always present (§11 aligned) + const steps = [ + '1) Cascading updates (PF + project.md + state.md + iterations + Release)', + '2) pace-learn knowledge extraction', + '3) dashboard.md incremental metrics', + '4) PF completion → release note', + '5) Iteration completion check (>90% → suggest retro)', + '6) First-CR review (teaching dedup)', + ]; + + // Step 7: conditional — only if sync-mapping exists and CR has external link + const syncMappingPath = `${projectDir}/.devpace/integrations/sync-mapping.md`; + if (existsSync(syncMappingPath)) { + try { + const content = readFileSync(filePath, 'utf-8'); + const hasExternalLink = /\*\*外部关联\*\*[：:]/.test(content); + if (hasExternalLink) { + steps.push(`7) External sync push: auto-execute /pace-sync push ${crName}`); + } + } catch { + // Read error — skip step 7 + } + } + + console.log(`devpace:post-merge ${crName} merged. Execute post-merge pipeline: ${steps.join(' ')}`); } } diff --git a/hooks/sync-push.mjs b/hooks/sync-push.mjs new file mode 100755 index 0000000..834c63d --- /dev/null +++ b/hooks/sync-push.mjs @@ -0,0 +1,88 @@ +#!/usr/bin/env node +/** + * sync-push.mjs — PostToolUse Hook + * Detects CR **actual state transitions** and reminds to sync with external tools. + * Uses a file-based cache (.devpace/.sync-state-cache) to compare old vs new state, + * so ordinary edits that don't change state are silently ignored. + * + * - State unchanged → silent exit (no noise) + * - State changed to merged → directive language (auto-execute) + * - State changed to other value → advisory suggestion + * + * Advisory only (exit 0) — never blocks workflow. + */ + +import { readFileSync, existsSync } from 'node:fs'; +import { basename } from 'node:path'; +import { + readStdinJson, getProjectDir, isCrFile, extractFilePath, readCrState, + readSyncStateCache, updateSyncStateCache, +} from './lib/utils.mjs'; + +const input = await readStdinJson(); +const projectDir = getProjectDir(); +const backlogDir = `${projectDir}/.devpace/backlog`; + +// Only act if .devpace exists and has backlog +if (!existsSync(backlogDir)) { + process.exit(0); +} + +// Extract file path from tool input +const filePath = extractFilePath(input); + +// Only care about CR files +if (!isCrFile(filePath, backlogDir)) { + process.exit(0); +} + +// No sync-mapping → no sync configured → silent exit +const syncMappingPath = `${projectDir}/.devpace/integrations/sync-mapping.md`; +if (!existsSync(syncMappingPath)) { + process.exit(0); +} + +// Read current CR state +const newState = readCrState(filePath); +if (!newState) { + process.exit(0); +} + +// Compare with cached state — only act on actual transitions +const crName = basename(filePath, '.md'); +const cache = readSyncStateCache(projectDir); +const oldState = cache.get(crName) || ''; + +if (oldState === newState) { + // State unchanged — silent exit (resolves noise problem, F11.8) + process.exit(0); +} + +// State actually changed — update cache first +updateSyncStateCache(projectDir, crName, newState); + +// Check if CR has external link +try { + const content = readFileSync(filePath, 'utf-8'); + const hasExternalLink = /\*\*外部关联\*\*[：:]/.test(content); + + if (!hasExternalLink) { + process.exit(0); + } + + // Extract external link info for the reminder + const linkMatch = content.match(/\*\*外部关联\*\*[：:]\s*\[([^\]]+)\]\(([^)]+)\)/); + const linkText = linkMatch ? linkMatch[1] : '外部实体'; + + if (newState === 'merged') { + // Directive language for merged — §11 step 7 close-loop + console.log(`devpace:sync-push ${crName} state transition: ${oldState || '(new)'}→merged, linked to ${linkText}. Auto-execute: /pace-sync push ${crName} (§11 step 7 — close Issue + done label + completion summary)`); + } else { + // Advisory suggestion for other transitions + console.log(`devpace:sync-push ${crName} state transition: ${oldState || '(new)'}→${newState}, linked to ${linkText}. Consider running /pace-sync push to sync status.`); + } +} catch { + // File read error — silent exit +} + +process.exit(0); diff --git a/knowledge/_schema/cr-format.md b/knowledge/_schema/cr-format.md index fe9ebeb..40125ce 100644 --- a/knowledge/_schema/cr-format.md +++ b/knowledge/_schema/cr-format.md @@ -7,7 +7,7 @@ ``` 文件名：CR-xxx.md（xxx 为自增数字，三位补零） 标题：自然语言描述（不含 ID） -必含：元信息 + 意图（Claude 渐进填充）+ 验证证据（可选，/pace-test accept 产出）+ 质量检查 checkbox + 事件表（含操作者列、交接列（可选）） +必含：元信息 + 意图（Claude 渐进填充）+ 验证证据（可选，/pace-test accept 产出）+ 质量检查 checkbox + 事件表（含操作者列、交接列（可选））+ 外部关联（可选，/pace-sync link 产出） 意图：用户原话 → 范围 → 验收条件（复杂度自适应格式） → 方案 → 约束（复杂度越高填充越完整） → 执行计划（L/XL 必须） 验收条件格式：简单=自由文本 · 标准=编号清单 · 复杂=Given/When/Then 歧义标记：[待确认: ...] 标记未确认的假设，Gate 2 前必须解决 @@ -32,6 +32,7 @@ - **分支**：[feature/branch-name] - **状态**：[created | developing | verifying | in_review | approved | merged | released] - **关联 Release**：[REL-xxx]（可选——纳入 Release 后填写） +- **外部关联**：[github:#42](https://github.com/owner/repo/issues/42)（可选——/pace-sync link 后填写） - **复杂度**：[S | M | L | XL]（可选——created→developing 时自动评估） - **关联**：（可选——存在依赖或关系时填写） - 阻塞：[CR-ID]（[原因]） @@ -253,6 +254,20 @@ CR 意图 section 使用溯源标记区分用户输入与 Claude 推断。溯源 - **变更影响**：/pace-change 影响分析时遍历所有关联关系类型，blocks 和 follows 影响最高，relates-to 作为参考信息 - **简化写法**：仅有一种关系时可省略 section 结构，直接写 `- **阻塞**：...` +## 外部关联字段 + +可选字段——由 `/pace-sync link` 自动写入，记录 CR 与外部实体的关联。 + +**格式**：`[平台:ID](https://平台URL)` +- 示例：`[github:#42](https://github.com/owner/repo/issues/42)` +- 示例：`[linear:PROJ-123](https://linear.app/team/issue/PROJ-123)` + +**规则**： +- 缺失时不影响任何流程（向后兼容） +- /pace-sync link 自动填写，用户也可手动编辑 +- /pace-sync push/status 读取此字段定位外部实体 +- 一个 CR 只关联一个外部实体（1:1 映射） + ## 命名规则 - 文件名：`CR-001.md`、`CR-002.md`...（三位补零自增） diff --git a/knowledge/_schema/integrations-format.md b/knowledge/_schema/integrations-format.md index 003775c..b54e276 100644 --- a/knowledge/_schema/integrations-format.md +++ b/knowledge/_schema/integrations-format.md @@ -7,7 +7,7 @@ ``` 文件：.devpace/integrations/config.md 可选文件——不存在时集成功能降级，核心流程不受影响 -包含：环境列表 + CI/CD 配置 + 版本管理 + 发布验证 + 监控配置 + 告警映射 +包含：环境列表 + CI/CD 配置 + 版本管理 + 发布验证 + 外部同步配置 + 监控配置 + 告警映射 写入规则：/pace-init 创建初始配置，人类按需更新 ``` @@ -76,6 +76,14 @@ devpace 在初始化和 Gate 4 执行时自动检测项目 CI 工具，按以下 - **覆盖率报告命令**：[从 CI 获取覆盖率的命令，如 `gh api repos/{owner}/{repo}/actions/artifacts`，可选] - **测试结果格式**：[junit-xml / json / custom，可选] +## 外部同步 + +- **平台**：[github | linear | jira | gitlab，可选] +- **连接**：[owner/repo 或项目标识，可选] +- **同步模式**：[push | pull | bidirectional，默认 push] +- **冲突策略**：[devpace-authoritative | external-authoritative | ask-user，默认 ask-user] +- **映射文件**：[sync-mapping.md 路径，默认 integrations/sync-mapping.md] + ## 监控 - **工具**：[监控工具，如 Grafana / DataDog / CloudWatch，可选] @@ -158,6 +166,16 @@ devpace 在初始化和 Gate 4 执行时自动检测项目 CI 工具，按以下 当此 section 存在时，`/pace-test` 可从 CI 系统拉取测试结果和覆盖率数据，作为本地测试的补充信号。 +### 外部同步 + +| 字段 | 说明 | 必填 | +|------|------|:----:| +| 平台 | 外部项目管理平台类型 | ❌ | +| 连接 | 平台项目标识（如 owner/repo） | ❌ | +| 同步模式 | push（仅推送）/ pull（仅拉取）/ bidirectional（双向） | ❌ | +| 冲突策略 | 两侧状态冲突时的处理策略 | ❌ | +| 映射文件 | 同步映射配置文件路径 | ❌ | + ### 告警映射 将外部告警等级映射到 devpace 的严重度和 CR 类型，供 /pace-feedback 自动设置默认值。 @@ -174,4 +192,5 @@ devpace 在初始化和 Gate 4 执行时自动检测项目 CI 工具，按以下 - /pace-release verify：无验证命令时，保持手动验证模式 - /pace-release branch：无发布分支配置时，所有操作在 main 分支完成 - /pace-release deploy：仅 1 个环境时直接部署，无晋升流程 +- /pace-sync：无"外部同步"配置时，提示运行 `/pace-sync setup` 配置 - 核心流程（CR 状态机、质量门、变更管理）完全不受影响 diff --git a/knowledge/_schema/state-format.md b/knowledge/_schema/state-format.md index 2a7df36..cbf7ea8 100644 --- a/knowledge/_schema/state-format.md +++ b/knowledge/_schema/state-format.md @@ -46,7 +46,7 @@ Claude 下次会话应该做什么的建议。人类可以修改此字段来指 用于版本兼容性检查。Claude 读取 state.md 时校验版本，确保与当前 Plugin 版本匹配。版本不匹配时提示用户但不阻断工作。 -合法版本值：语义化版本 `X.Y.Z`，当前最新 `1.4.0`。 +合法版本值：语义化版本 `X.Y.Z`，当前最新 `1.5.0`。 ### 教学标记（文件末尾，版本标记同行或相邻） diff --git a/knowledge/_schema/sync-mapping-format.md b/knowledge/_schema/sync-mapping-format.md new file mode 100644 index 0000000..15d2b7f --- /dev/null +++ b/knowledge/_schema/sync-mapping-format.md @@ -0,0 +1,152 @@ +# 同步映射配置格式契约 + +> **职责**：定义 integrations/sync-mapping.md 的结构。/pace-sync setup 创建，/pace-sync link 更新关联记录。 + +## §0 速查卡片 + +``` +文件：.devpace/integrations/sync-mapping.md +可选文件——不存在时同步功能不可用，核心流程不受影响 +包含：平台配置 + CR 状态映射 + 实体映射 + Gate 结果同步 + 关联记录 +写入规则：/pace-sync setup 创建，/pace-sync link 更新关联记录，/pace-sync push 更新最后同步时间 +``` + +## 文件结构 + +```markdown +# 同步映射配置 + +## 平台 + +- **类型**：[github | linear | jira | gitlab] +- **连接**：[owner/repo 或项目标识，如 myorg/myrepo] +- **同步模式**：[readonly | push | pull | bidirectional] +- **冲突策略**：[devpace-authoritative | external-authoritative | ask-user] + +## CR 状态映射 + +| devpace 状态 | 外部状态 | 同步方向 | 备注 | +|-------------|---------|---------|------| +| created | 待办 | ↔ | GitHub: `backlog` 标签 · Linear: Backlog 状态 | +| developing | 进行中 | ↔ | GitHub: `in-progress` 标签 · Linear: In Progress 状态 | +| verifying | 待审查 | → | GitHub: `needs-review` 标签 · Linear: In Review 状态 | +| in_review | 等待审批 | → | GitHub: `awaiting-approval` 标签 · Linear: In Review 状态 | +| approved | 已批准 | → | GitHub: `approved` 标签 · Linear: Done 状态 | +| merged | 已完成 | ↔ | GitHub: 关闭 Issue + `done` 标签 · Linear: Done 状态 | +| released | 已发布 | → | GitHub: `released` 标签 · Linear: Done 状态 | +| paused | 搁置 | ↔ | GitHub: `on-hold` 标签 · Linear: Paused 状态 | + +## 实体映射 + +| devpace 概念 | 外部概念 | 说明 | +|-------------|---------|------| +| BR（业务需求） | Milestone | 业务需求对应外部里程碑 | +| PF（产品功能） | Epic / 大 Issue | 产品功能对应外部 Epic 或大 Issue | +| CR（变更请求） | Issue | 变更请求对应外部 Issue | +| Release | Release | Release 对应外部 Release（如 GitHub Release） | + +## Gate 结果同步 + +### Gate 1（开发完成门禁） + +| 结果 | 外部动作 | 说明 | +|------|---------|------| +| 通过 | Comment + gate-1-passed 标签 | 在关联 Issue 添加通过评论和标签 | +| 未通过 | Comment（含失败摘要） | 在关联 Issue 添加失败原因评论 | + +### Gate 2（审批门禁） + +| 结果 | 外部动作 | 说明 | +|------|---------|------| +| 通过 | PR Review（approve） | 在关联 PR 提交 approve review | +| 未通过 | Comment（含未通过项） | 在关联 Issue 添加未通过详情评论 | + +### Gate 3（发布门禁） + +| 结果 | 外部动作 | 说明 | +|------|---------|------| +| 待处理 | PR Review（request changes）+ review 摘要 | 在关联 PR 请求变更并附摘要 | +| 通过 | Comment + gate-3-passed 标签 | 在关联 Issue 添加通过评论和标签 | + +## 关联记录 + + + +| CR | 外部实体 | 关联时间 | 最后同步 | +|----|---------|---------|---------| +| [CR-xxx] | [平台#编号，如 github#42] | [YYYY-MM-DD HH:mm] | [YYYY-MM-DD HH:mm] | +``` + +## 字段说明 + +### 平台 + +| 字段 | 说明 | 必填 | +|------|------|:----:| +| 类型 | 外部平台标识，支持 github / linear / jira / gitlab | ✅ | +| 连接 | 平台连接标识，格式取决于平台类型（如 GitHub 为 owner/repo） | ✅ | +| 同步模式 | 数据流向控制：readonly（只读）/ push（仅推送）/ pull（仅拉取）/ bidirectional（双向） | ✅ | +| 冲突策略 | 双向同步时的冲突解决方式：devpace-authoritative / external-authoritative / ask-user | ❌ | + +**冲突策略说明**： +- `devpace-authoritative`：冲突时以 devpace 状态为准（默认值） +- `external-authoritative`：冲突时以外部平台状态为准 +- `ask-user`：冲突时暂停并询问用户决定 + +**同步模式说明**： +- `readonly`：仅读取外部状态，不做任何写入。适合观察阶段 +- `push`：devpace 状态变更时推送到外部，不读取外部变更 +- `pull`：从外部拉取状态变更到 devpace，不推送 +- `bidirectional`：双向同步，需配合冲突策略 + +### CR 状态映射 + +| 字段 | 说明 | 必填 | +|------|------|:----:| +| devpace 状态 | devpace CR 状态机中的状态值 | ✅ | +| 外部状态 | 对应的外部平台状态语义（具体执行见适配器文件） | ✅ | +| 同步方向 | ↔（双向）或 →（仅 devpace→外部） | ✅ | +| 备注 | 映射规则的补充说明 | ❌ | + +**同步方向与同步模式的关系**：状态映射中的同步方向是逐状态的精细控制。实际生效的方向取"平台同步模式"与"状态同步方向"的交集。例如平台同步模式为 push 时，即使状态映射标记为 ↔，实际也只执行 → 方向。 + +### 实体映射 + +| 字段 | 说明 | 必填 | +|------|------|:----:| +| devpace 概念 | devpace 价值链中的实体（BR / PF / CR / Release） | ✅ | +| 外部概念 | 对应的外部平台实体类型 | ✅ | +| 说明 | 映射关系的补充说明 | ❌ | + +### Gate 结果同步 + +| 字段 | 说明 | 必填 | +|------|------|:----:| +| 结果 | Gate 检查的结果状态 | ✅ | +| 外部动作 | 在外部平台执行的动作（Comment / Label / PR Review） | ✅ | +| 说明 | 动作的补充说明 | ❌ | + +### 关联记录 + +| 字段 | 说明 | 必填 | +|------|------|:----:| +| CR | devpace CR 编号（CR-xxx） | ✅ | +| 外部实体 | 外部平台实体标识（格式：平台#编号，如 github#42） | ✅ | +| 关联时间 | 首次建立关联的时间戳（YYYY-MM-DD HH:mm） | ✅ | +| 最后同步 | 最近一次成功同步的时间戳（YYYY-MM-DD HH:mm） | ✅ | + +## 降级行为 + +当 `integrations/sync-mapping.md` 不存在时： +- /pace-sync：所有子命令提示先运行 `/pace-sync setup` 创建映射配置 +- /pace-dev、/pace-change：不显示同步提醒 +- /pace-test：Gate 结果不推送到外部平台 +- /pace-release：Release 不同步到外部平台 +- 核心流程（CR 状态机、质量门、变更管理）完全不受影响 + +当映射配置存在但部分 section 缺失时： +- 缺少"平台"：视为配置损坏，所有子命令提示重新运行 `/pace-sync setup` +- 缺少"CR 状态映射"：状态变更不同步，其他功能正常 +- 缺少"实体映射"：仅同步 CR 级别，BR/PF/Release 不同步 +- 缺少"Gate 结果同步"：Gate 检查正常执行但结果不推送到外部 +- 缺少"关联记录"：视为无已关联实体，/pace-sync link 时自动创建此 section diff --git a/knowledge/teaching-catalog.md b/knowledge/teaching-catalog.md index d96fa3a..ca11e8c 100644 --- a/knowledge/teaching-catalog.md +++ b/knowledge/teaching-catalog.md @@ -13,3 +13,6 @@ | 功能树更新 | 首次更新 project.md 功能树时 | "（功能树自动记录目标到代码的关系，随工作自然生长。）" | `tree` | | merged 连锁更新 | 首次执行 merged 后连锁更新时 | "（合并后自动更新所有关联状态，保持一致。）" | `merge` | | AI 验收验证 | 首次执行 /pace-test accept 时 | "（accept 为人类审批提供逐条验收证据和改进建议，让 Gate 3 更高效。详见 /pace-test。）" | `accept` | +| 同步配置 | 首次运行 /pace-sync setup 时 | "（同步配置让 devpace 状态自动映射到 GitHub Issue 标签。）" | `sync_setup` | +| 状态推送 | 首次运行 /pace-sync push 时 | "（push 将 CR 状态变化同步到外部工具，保持项目管理工具和实际进度一致。）" | `sync_push` | +| Issue 自动创建 | 首次在 CR 创建后提议创建外部 Issue 时 | "（检测到同步配置，可以自动在 GitHub 创建对应 Issue 并关联。）" | `sync_create` | diff --git a/rules/devpace-rules.md b/rules/devpace-rules.md index 7d59918..d870c43 100644 --- a/rules/devpace-rules.md +++ b/rules/devpace-rules.md @@ -11,6 +11,7 @@ | §13.5 | 始终生效 | 子 Agent 鲁棒性（inline 回退）与透明度（变更摘要） | | §14 | 对应目录存在时生效 | 发布管理 / 运维反馈 / 集成管理（条件生效） | | §15 | 始终生效 | 渐进教学（首次触发系统行为时附带解释） | +| §16 | sync-mapping.md 存在时生效 | 同步管理（条件生效） | ## §0 速查卡片 @@ -34,14 +35,14 @@ ### 节奏 + 风险 + 质量 脉搏：每 5 checkpoint | ≤3 条/会话 | High 暂停等人（§10） 质量：命令+意图+对抗→自修复→Gate 3 人类审批（IR-2）（§2, §14） -可选：Release/集成/反馈——目录存在时生效（§14）| 渐进教学——首次触发附 1 句（§15） +可选：Release/集成/反馈/同步——目录或文件存在时生效（§14, §16）| 渐进教学——首次触发附 1 句（§15） ### 命令分层 | 层级 | 命令 | |------|------| | 核心 | /pace-init · /pace-dev · /pace-status · /pace-review · /pace-next | -| 进阶 | /pace-change · /pace-plan · /pace-retro · /pace-guard | +| 进阶 | /pace-change · /pace-plan · /pace-retro · /pace-guard · /pace-sync | | 专项 | /pace-release · /pace-test · /pace-feedback · /pace-role · /pace-theory · /pace-trace | | 系统 | pace-learn · pace-pulse — Claude 自动调用 | @@ -290,11 +291,11 @@ Claude 在推进模式中主动监控研发节奏，检测异常信号并输出 ## §11 迭代自动节奏 -> **核心**：merged 后自动执行 6 步管道（连锁更新 + 知识积累 + 度量 + Release + 完成度 + 首次回顾）。 +> **核心**：merged 后自动执行 7 步管道（连锁更新 + 知识积累 + 度量 + Release + 完成度 + 首次回顾 + 外部同步）。 ### merged 后自动管道 -CR 进入 merged 后，Claude 自动执行 6 步管道（不需用户指令）： +CR 进入 merged 后，Claude 自动执行 7 步管道（不需用户指令）： 1. **连锁更新**：PF 状态 + project.md 功能树 + state.md + iterations/current.md + Release 纳入判断 2. **即时知识积累**：`pace-learn` 提取 pattern → insights.md @@ -302,6 +303,7 @@ CR 进入 merged 后，Claude 自动执行 6 步管道（不需用户指令） 4. **Release Note 检查**：PF 所有 CR 均 merged → 变更摘要追加 iterations/current.md 5. **迭代完成度检查**：PF 完成率 >90% → 建议 `/pace-retro` 后 `/pace-plan` 6. **首个 CR 回顾**（教学标记 `first_merged` 去重）：附 3 行说明 +7. **外部同步推送**（sync-mapping.md 存在 + 当前 CR 有外部关联时）：自动 push → 关闭 Issue + `done` 标签 + 语义完成摘要 Comment ### 迭代节奏信号 @@ -368,6 +370,7 @@ forked Agent 完成后输出变更摘要（改了什么 + 关键决策 + 注意 | 发布管理 | `.devpace/releases/` 存在 | `skills/pace-release/release-procedures-lifecycle.md` + `release-procedures-expert.md` | | 运维反馈 | `.devpace/releases/` 存在 | `skills/pace-feedback/feedback-procedures.md` | | 集成管理 | `.devpace/integrations/config.md` 存在 | `skills/pace-release/release-procedures-expert.md` | +| 同步管理 | `.devpace/integrations/sync-mapping.md` 存在 | `skills/pace-sync/sync-procedures.md` | Release 是可选功能——未配置时 merged 仍是有效终态。集成完全可选，手动摄入始终可用。 @@ -405,3 +408,36 @@ Claude 在首次触发系统行为时，附加 1 句话解释"为什么"，帮 3. **更新标记**：教学后立即在 state.md 的 taught 注释中追加该标记值 4. **格式要求**：教学内容用括号包裹，紧跟行为输出之后，不独立成段 5. **标记缺失兼容**：state.md 无 taught 注释时，视为全部未教，首次教学时创建注释 + +## §16 同步管理（条件生效） + +> **核心**：CR 状态变化时提醒同步，手动 push 为主，不自动修改外部系统。 + +### 生效条件 + +`.devpace/integrations/sync-mapping.md` 存在时生效。不存在时整个 §16 静默跳过。 + +### 同步行为规则 + +1. **手动推送为主**（Phase 18 MVP）：CR **实际状态转换**后提醒推送（sync-push Hook 缓存比对，非每次写入触发），不自动执行外部操作 +2. **关联管理**：`/pace-sync link` 建立 CR ↔ 外部实体 1:1 映射，记录在 CR 文件和 sync-mapping.md +3. **创建与解除**：`/pace-sync create` 从 CR 创建外部工作项并自动关联；`/pace-sync unlink` 解除关联并清理映射记录 +4. **状态映射**：推送时按 sync-mapping.md 状态映射表翻译 devpace 状态为外部标签/操作 +5. **只推不拉**（Phase 18 MVP）：仅支持 devpace → 外部方向，不消费外部状态变化 +6. **幂等操作**：重复 push 同一状态不产生副作用（标签已存在则跳过） +7. **降级静默**：gh CLI 不可用时 push 报错并提示安装，不阻断核心工作流 +8. **副产物非前置三阶段**（渐进消除手动前置）： + - pace-init 检测 git remote 时提议同步配置（Step 8） + - CR 创建时提议创建外部 Issue（sync-mapping.md 存在时，自主级别分化） + - merged 时自动推送（§11 第 7 步，post-cr-update Hook 指令 + sync-push Hook 安全网双层保障） + +### 与现有规则的协调 + +- §2 推进模式状态转换后 → sync-push Hook 缓存比对检测实际转换，输出建议性提醒（advisory，不阻断） +- §11 merged 后连锁更新第 7 步 → post-cr-update Hook 输出指令性管道（含第 7 步外部同步），sync-push Hook 作为安全网双层保障 +- §14 发布管理 → Release 同步（Phase 19） +- Gate 1/2/3 结果同步：Gate 完成后若 CR 有外部关联，自动推送结果（详见 sync-procedures.md §4.8） + +### 适用范围更新 + +§16 加入 §14 的"条件生效"模式：目录/文件存在时自动生效，不存在时静默跳过。 diff --git a/skills/pace-change/change-procedures.md b/skills/pace-change/change-procedures.md index 9de6faf..2f1f78b 100644 --- a/skills/pace-change/change-procedures.md +++ b/skills/pace-change/change-procedures.md @@ -193,6 +193,19 @@ Claude 根据以下信号自动建议分流决策（用户可覆盖）： 无迭代文件时，变更事件记录到 CR 文件的事件表。 +### Step 4：外部同步检查 + +变更操作（pause/resume/priority change 等）执行完成后： + +1. 检查受影响 CR 是否有外部关联（读取 CR 文件的"外部关联"字段） +2. 有关联 → 提醒用户："CR-{id} 已关联外部 Issue #{number}，建议运行 `/pace-sync push CR-{id}` 同步状态变更。" +3. 无关联 → 静默跳过 + +**规则**： +- 仅提醒，不自动执行 push（Phase 18 MVP 行为） +- sync-mapping.md 不存在时跳过整个步骤 +- 批量变更时合并提醒："N 个已关联 CR 的状态已变更，建议运行 `/pace-sync push` 同步。" + ## paused 状态规则 paused 状态的完整定义见 `knowledge/_schema/cr-format.md`。操作要点： diff --git a/skills/pace-dev/dev-procedures.md b/skills/pace-dev/dev-procedures.md index 994095b..dbd6802 100644 --- a/skills/pace-dev/dev-procedures.md +++ b/skills/pace-dev/dev-procedures.md @@ -14,6 +14,22 @@ - **风险预扫描**：L/XL 必须 + S 多文件/M 按 insights 匹配触发（guard-procedures.md scan） - **功能发现与执行透明摘要**：嵌入式新功能捕获 + Human Transparency 输出 +## 同步关联提议（sync-mapping.md 存在时） + +CR 创建完成后，如果 `.devpace/integrations/sync-mapping.md` 存在： + +1. 自然语言提议："是否要为 CR-{id} 创建 GitHub Issue 并关联？" + - 用户同意 → 执行 `/pace-sync create CR-{id}`（复用 sync-procedures §7） + - 用户拒绝 → 静默跳过 +2. 首次提议后标记教学 `sync_create`（每项目仅提议前 3 次，之后静默跳过或自动创建） + +**自主级别分化**： +- 辅助级：每次询问 +- 标准级：前 3 次询问，之后静默跳过 +- 自主级：自动创建并关联（不询问） + +**规则**：sync-mapping.md 不存在时完全跳过，不提醒配置同步。 + ## 意图检查点 当 CR 从 created 转入 developing 时，Claude 自主完成意图检查点： diff --git a/skills/pace-init/SKILL.md b/skills/pace-init/SKILL.md index c053c2a..00d368b 100644 --- a/skills/pace-init/SKILL.md +++ b/skills/pace-init/SKILL.md @@ -1,113 +1,62 @@ --- -description: Use when user says "初始化", "pace-init", "开始追踪", "初始化研发管理", "新项目", "项目管理", "set up devpace", or wants to set up project development tracking for a new or existing project. +description: Use when user says "初始化", "pace-init", "开始追踪", "初始化研发管理", "新项目", "项目管理", "set up devpace", "健康检查 devpace", "重置 devpace", "预览初始化", or wants to set up, verify, or reset project development tracking. allowed-tools: AskUserQuestion, Write, Read, Glob, Bash -argument-hint: "[项目名称] [full] [--from <文档路径>] [--import-insights <导出文件路径>]" +argument-hint: "[项目名称] [full] [--from <路径>...] [--import-insights <路径>] [--verify [--fix]] [--dry-run] [--reset [--keep-insights]] [--export-template] [--from-template <路径>] [--interactive]" model: sonnet disable-model-invocation: true --- # /pace-init — 初始化项目开发节奏管理 -从模板初始化当前项目的 `.devpace/` 目录。默认执行最小初始化（仅需项目名 + 描述），`full` 参数执行完整流程，`--from` 参数从需求文档自动生成功能树。详细迁移和配置流程见 `init-procedures.md`。 +从模板初始化当前项目的 `.devpace/` 目录。默认执行最小初始化（自动检测项目生命周期阶段，按阶段适配行为），`full` 执行分阶段完整流程，`--from` 从文档自动生成功能树。支持 `--verify`（健康检查）、`--reset`（重置）、`--dry-run`（预览）等子命令。 ## 输入 -$ARGUMENTS：可选。格式为 `[项目名称]`、`[项目名称] full` 或 `[项目名称] --from <文档路径>`。未提供名称时询问。 +$ARGUMENTS：可选。格式： -## 流程 - -### Step 0：版本迁移检测 - -- 无 `.devpace/state.md` → 全新初始化（Step 1） -- 有 state.md + version=0.9.0 → 提示已初始化，询问重置 -- 有 state.md + version=0.2.0~0.8.0 → 提示已初始化，询问重置（兼容，无迁移） -- 有 state.md + version=0.1.0/缺失 → v0.1→v0.9 迁移（详见 `init-procedures.md`） - -### Step 1：信息收集（最小） - -确认项目根目录。收集： -- **项目名称**（$ARGUMENTS 提供或询问） -- **一句话描述**（询问："用一句话描述这个项目做什么？"） - -仅此两项。业务目标、MoS、功能树等后续自然生长。 - -### Step 2：生成 .devpace/（最小） - -``` -.devpace/ -├── state.md # 仅 "目标: [描述], 无进行中工作" -├── project.md # 桩: 项目名 + 描述, 空价值树 -├── backlog/ -└── rules/ - ├── workflow.md # 标准模板 - └── checks.md # 从项目类型自动检测（package.json→npm test 等） -``` - -**不创建**：`iterations/`、`metrics/`、`releases/`、`integrations/`——这些在首次使用对应功能时按需创建。 +- `[项目名称]` — 最小初始化（默认，生命周期感知） +- `[项目名称] full` — 分阶段完整流程 +- `[项目名称] --from <路径>...` — 从文档生成功能树（支持目录和多文件） +- `--verify [--fix]` — 健康检查（可选自动修复） +- `--dry-run` — 预览初始化结果，不写入文件 +- `--reset [--keep-insights]` — 重置 .devpace/ +- `--export-template` — 导出当前配置为可复用模板 +- `--from-template <路径>` — 从模板初始化 +- `--import-insights <路径>` — 导入跨项目经验 +- `--interactive` — 强制对话模式（覆盖自动检测行为） -### Step 3：确认 - -输出初始化摘要，然后展示"接下来会发生什么"预览： - -``` -初始化完成。接下来你可以： -- 说"帮我实现 X" → 我会自动跟踪这个任务 -- 说"加一个 Y" → 我会分析影响再调整 -- 说"做到哪了" → 我报告进度 -``` - -建议在 `.gitignore` 中添加 `.devpace/`（如果用户不想版本控制状态文件）。 - -## `/pace-init full` 完整流程 - -当参数含 `full` 时，执行完整信息收集（兼容 v0.3.0 行为）： - -1. 项目名称 + 描述 -2. **环境探测**（自动）：项目类型、MCP 感知、CI/CD 检测、Git 策略（详见 `init-procedures.md` "环境探测"章节） -3. 业务目标 + MoS -4. 实施路径 -5. 产品功能 -6. 发布配置（可选，详见 `init-procedures.md`） -7. 质量检查引导 - -生成完整目录结构： +## 流程 -``` -.devpace/ -├── state.md · project.md · backlog/ · releases/ · integrations/ -├── iterations/current.md · rules/{workflow,checks}.md -└── metrics/dashboard.md -``` +### Step 0：前置检查与路由 -## `/pace-init --from <文档路径>` 文档驱动初始化 +**子命令路由**（优先级高于初始化流程）： -当参数含 `--from` 时，从需求文档（PRD/README/设计文档）自动解析并生成 BR→PF→CR 功能树： +- `--verify` → 健康检查流程 +- `--reset` → 重置流程 +- `--export-template` / `--from-template` → 模板管理流程 -### 流程 +**标志处理**： -1. **读取文档**：读取指定路径的文档文件（支持 .md/.txt/.pdf 等） -2. **提取需求**：AI 解析文档，识别业务目标、功能模块、用户场景 -3. **生成功能树**：将提取的需求映射为 devpace 概念模型： - - 业务目标/核心价值 → BR（业务需求） - - 功能模块/特性描述 → PF（产品功能） - - 具体任务/实现项 → CR（变更请求）初始列表 -4. **用户确认**：展示生成的功能树结构，等待用户确认或调整 -5. **写入 project.md**：确认后写入 `.devpace/project.md` 的价值功能树 +- `--dry-run` → 设置 dry-run 标志，继续正常流程但不写入任何文件 -### 差异化 +**版本与状态检测**：检查 `.devpace/state.md` 存在性和版本标记，决定全新初始化、增量迁移或提示重置（规则见 `init-procedures-core.md` §8）。 -与扁平任务列表不同，`--from` 生成的是 BR→PF→CR 价值链： -- 每个 CR 可追溯到所属的 PF 和 BR -- 功能之间的依赖关系被识别和记录 -- 变更管理可追踪影响到业务目标级别 +### Step 1-4：初始化执行 -### 注意事项 +根据参数读取对应规程文件执行（仅读取匹配路径的规程文件）： -- 文档内容越结构化，解析结果越准确 -- 模糊的描述会被标记为"需澄清"，生成后用户可调整 -- 生成的 CR 初始列表仅为建议，不自动创建 CR 文件（用户 /pace-dev 时才创建） -- 可与 `full` 参数组合使用：`/pace-init myproject full --from prd.md` +| 参数 | 执行规程 | +|------|---------| +| （默认）`[项目名]` | `init-procedures-core.md` | +| `full` | `init-procedures-core.md` + `init-procedures-full.md` | +| `--from <路径>...` | `init-procedures-core.md` + `init-procedures-from.md` | +| `--import-insights <路径>` | `init-procedures-from.md`（可与初始化组合或独立使用） | +| `--verify [--fix]` | `init-procedures-verify.md` | +| `--dry-run` | `init-procedures-dryrun.md` | +| `--reset [--keep-insights]` | `init-procedures-reset.md` | +| `--export-template` / `--from-template` | `init-procedures-template.md` | +| （迁移触发时） | `init-procedures-core.md` §8 迁移框架 | ## 输出 -初始化完成的 `.devpace/` 目录 + 确认摘要。 +初始化完成的 `.devpace/` 目录 + 确认摘要。`--dry-run` 时仅输出预览。`--verify` 时输出健康报告。`--reset` 时输出清理确认。 diff --git a/skills/pace-init/init-procedures-checks.md b/skills/pace-init/init-procedures-checks.md new file mode 100644 index 0000000..37edd81 --- /dev/null +++ b/skills/pace-init/init-procedures-checks.md @@ -0,0 +1,84 @@ +# 工具链检测参考数据 + +> **职责**：工具链精准检测的映射表和默认检查项建议。核心行为规则（何时触发、如何生成 checks.md）见 `init-procedures-core.md` §9。 + +## 生态系统精准检测表 + +### Node.js + +| 检测源 | 检测字段 | 生成命令 | +|--------|---------|---------| +| package.json devDependencies | `vitest` | `npx vitest run` | +| package.json devDependencies | `jest` | `npx jest` | +| package.json devDependencies | `mocha` | `npx mocha` | +| package.json scripts | `test` 脚本 | `npm test`（兜底，仅当无上述工具时） | +| package.json devDependencies | `@biomejs/biome` | `npx biome check .` | +| `.eslintrc*` 或 `eslint.config.*` | 文件存在 | `npx eslint .` | +| `.prettierrc*` | 文件存在 | `npx prettier --check .` | +| package.json devDependencies | `typescript` | `npx tsc --noEmit` | + +### Python + +| 检测源 | 检测字段 | 生成命令 | +|--------|---------|---------| +| pyproject.toml `[tool.pytest]` | section 存在 | `pytest` | +| pyproject.toml `[tool.ruff]` | section 存在 | `ruff check .` | +| pyproject.toml `[tool.mypy]` | section 存在 | `mypy .` | +| pyproject.toml `[tool.pyright]` | section 存在 | `pyright` | +| setup.cfg `[flake8]` | section 存在 | `flake8` | +| pyproject.toml dependencies | `bandit` | `bandit -r src/` | + +### Go + +| 检测源 | 检测字段 | 生成命令 | +|--------|---------|---------| +| go.mod | 文件存在 | `go test ./...` | +| .golangci.yml | 文件存在 | `golangci-lint run` | +| go.mod | 文件存在 | `go vet ./...` | + +### Rust + +| 检测源 | 检测字段 | 生成命令 | +|--------|---------|---------| +| Cargo.toml | 文件存在 | `cargo test` | +| Cargo.toml | 文件存在 | `cargo clippy -- -D warnings` | +| Cargo.toml | 文件存在 | `cargo audit`（如 cargo-audit 可检测） | + +## 通用规则 + +- 未检测到具体工具 → 保留通用占位符 `{{CHECK_COMMAND}}` +- 生成的命令必须直接可执行（不需要额外安装） +- 安全检查建议作为注释包含（``），用户可取消注释启用 +- 最小初始化时自动生成不询问；`--full` 模式时引导用户确认和补充 + +## 默认检查项建议 + +| 项目类型 | 意图检查建议 | 安全检查建议 | +|---------|-------------|-------------| +| Node.js | "所有导出函数有 JSDoc" | `npm audit --audit-level=high` | +| Python | "所有公共函数有 docstring" | `bandit -r src/` | +| Go | "所有导出函数有注释" | `gosec ./...` | +| Rust | "所有 pub 函数有文档注释" | `cargo audit` | +| 通用 | "单个函数不超过 50 行" | Claude 检查"代码中不含硬编码密钥" | + +## 检查项格式 + +checks.md 支持两种检查类型（格式定义见 `knowledge/_schema/checks-format.md`）： + +- **命令检查**：`检查方式：[bash 命令]`——exit code 判定（0=通过） +- **意图检查**：`检查方式：Claude 检查 [自然语言规则]`——Claude 阅读变更代码对照规则判定 + +```markdown +## 质量检查 + +### Gate 1：代码质量（developing → verifying） +- [ ] [检查名称]：`[命令]` +- [ ] [检查名称]：Claude 检查 [自然语言规则] + +### Gate 2：集成验证（verifying → in_review） +- [ ] [检查名称]：`[命令]` +- [ ] [检查名称]：Claude 检查 [自然语言规则] + +### Gate 3：人类审批（in_review → approved） +- [ ] 人类审批：Code Review 通过 +``` diff --git a/skills/pace-init/init-procedures-core.md b/skills/pace-init/init-procedures-core.md new file mode 100644 index 0000000..6e9f5a6 --- /dev/null +++ b/skills/pace-init/init-procedures-core.md @@ -0,0 +1,387 @@ +# 初始化核心规程 + +> **职责**：初始化和迁移的核心执行规则。覆盖生命周期检测、最小初始化、CLAUDE.md 合并、校验、引导、迁移、质量检查和 Monorepo 感知。 + +## §0 速查卡片 + +- **本文件**：核心规程——生命周期检测、Git 策略检测、最小初始化、CLAUDE.md 合并、校验、引导、迁移、质量检查引导、Monorepo +- **init-procedures-checks.md**：工具链检测参考数据——生态系统精准检测表、默认检查项建议、检查项格式 +- **init-procedures-full.md**：`full` 模式专用——环境探测、分阶段引导、发布配置收集 +- **init-procedures-from.md**：`--from` / `--import-insights` 专用——文档解析、经验导入 +- **init-procedures-verify.md**：`--verify` 健康检查 +- **init-procedures-reset.md**：`--reset` 重置 +- **init-procedures-dryrun.md**：`--dry-run` 预览 +- **init-procedures-template.md**：`--export-template` / `--from-template` 模板管理 + +## §1 项目生命周期检测 + +### 信号检测 + +通过以下信号组合判定项目生命周期阶段（无需用户告知）： + +| 信号 | 检测方式 | 阶段指向 | +|------|---------|---------| +| git commit 数量 | `git rev-list --count HEAD 2>/dev/null` | 0-5 → 新项目, 5-100 → 开发中, 100+ → 成熟 | +| git tags 存在 | `git tag --list 2>/dev/null` | 有版本标签（vX.Y.Z / X.Y.Z）→ 已发布 | +| CHANGELOG.md | 文件存在性检测 | 存在 → 已发布或接近发布 | +| 未合并分支数 | `git branch --no-merged main 2>/dev/null \| wc -l` | >0 → 有进行中工作 | +| 部署配置 | `fly.toml` / `app.yaml` / `serverless.yml` / `k8s/` / `terraform/` / `Procfile` | 存在 → 已发布或准备发布 | +| 源文件数量 | 按主要语言后缀统计（.js/.ts/.py/.go/.rs/.java） | <10 → 新项目, 10-100 → 开发中, 100+ → 成熟 | + +### 阶段判定逻辑 + +按优先级从高到低判定： + +1. **阶段 C（已发布）**：有版本 tags（匹配 `v*` 或 `[0-9]*.[0-9]*` 模式）**或** CHANGELOG.md 存在 **或** 有部署配置文件 +2. **阶段 B（开发中）**：不满足阶段 C **且**（commit 数 > 5 **或** 有未合并分支 **或** 源文件数 ≥ 10） +3. **阶段 A（新项目）**：不满足阶段 C 和 B（commit ≤ 5 且无 tags 且源文件 < 10） + +**非 git 仓库**：无 `.git/` → 默认阶段 A。 + +**判定结果输出**：用一句话交代，不暴露阶段标签。示例： +- 阶段 A："这是一个全新项目，采用极简初始化。" +- 阶段 B："检测到已有 47 次提交和 3 条活跃分支，已识别在研工作。" +- 阶段 C："检测到已有 47 次提交和 3 个版本标签的项目，已自动配置版本管理和发布追踪。" + +### 阶段 A：新项目策略 + +**核心原则**：极简启动，零提问优先。 + +**项目名称自动检测**（按优先级尝试）： + +1. `package.json` → `name` 字段 +2. `pyproject.toml` → `[project].name` +3. `go.mod` → `module` 路径最后一段 +4. `Cargo.toml` → `[package].name` +5. git remote → `git remote get-url origin` 提取仓库名 +6. 当前目录名 + +**项目描述自动检测**（按优先级尝试）： + +1. `package.json` → `description` 字段 +2. `pyproject.toml` → `[project].description` +3. `README.md` → 第一段非标题、非徽章文本（限 100 字符） + +**信息收集决策**： + +- 两项均可推断 → **直接生成，仅输出确认摘要**，不提问 +- 仅缺一项 → 只问缺失项 +- 两项均缺 → 依次询问（先名称后描述） + +**state.md 模式**：简单（5-8 行），使用标准模板。 + +**引导语**："试试说'帮我实现 XXX'，devpace 会自动开始追踪。" + +### 阶段 B：开发中项目策略 + +在阶段 A 基础上增加以下检测和预填充： + +1. **目录结构推断功能模块**： + - 扫描 `src/` 一级子目录（如 `auth/`、`billing/`、`api/`） + - 每个子目录作为一个 PF 候选写入 project.md 价值功能树 + - 标注 `` + - 无 `src/` 目录 → 跳过此步 + +2. **在研工作识别**： + - `git branch --no-merged main 2>/dev/null | head -5` 获取未合并分支列表 + - 输出候选列表供用户确认 + - 用户确认后为每个分支在 state.md "当前工作" section 添加条目 + - 不自动创建 CR 文件（用户可通过 /pace-dev 逐一处理） + +3. **README 信息提取**： + - Features / 功能 section → PF 候选 + - Non-Goals / 不做 / Out of Scope section → project.md "范围: 不做" + - 仅在 README.md 存在且有结构化内容时执行 + +4. **Git 策略检测**： + - 从 `--full` 专属提升为阶段 B 默认行为 + - 按上方"Git 策略检测"规则执行 + - 结果写入 context.md "开发流程" section + +5. **state.md 模式**：中等（10-12 行），含当前工作候选 + +### 阶段 C：已发布项目策略 + +在阶段 B 基础上增加以下自动配置： + +1. **版本管理自动配置**： + - 从 git tags 推断 tag 格式（`vX.Y.Z` 或 `X.Y.Z`）+ 当前版本号（最新 tag） + - 从 `package.json` / `pyproject.toml` / `Cargo.toml` 推断版本文件路径 + - 直接写入 `integrations/config.md` 版本管理 section，不提问 + +2. **发布分支自动识别**： + - `git branch -a | grep -E 'release/|hotfix/'` 检测分支模式 + - 存在 → 自动配置 integrations/config.md + 标注 workflow.md hotfix 路径可用 + +3. **环境列表推断**： + - 从 `.env.staging`、`.env.production` 等文件名 → 推断环境列表 + - 从部署配置文件内容（fly.toml 的 `[env]`、k8s manifest 的 namespace 等）→ 补充 + - 写入 integrations/config.md 环境 section + +4. **发布历史种子数据**： + - `git tag --sort=-version:refname | head -5` 获取最近 5 个版本 tag + - 配合 `git log --format="%ai" -1` 获取每个 tag 的日期 + - 写入 metrics/dashboard.md DORA 基线（标注 ``） + - 目录不存在则自动创建 + +5. **CHANGELOG 解析**（CHANGELOG.md 存在时）： + - 提取最近版本的功能/修复条目 + - 作为 BR/PF 种子展示给用户确认 + - 用户确认后写入 project.md + +6. **健康检查端点探测**： + - 搜索源代码中的 `/health`、`/ping`、`/readyz` 路由定义 + - 找到 → 建议作为发布验证命令写入 checks.md + +7. **pace-sync 推荐引导**： + - 阶段 C 将同步提议从"可选"提升为"推荐" + - 措辞调整："已发布项目通常需要外部同步，建议运行 `/pace-sync setup` 配置。" + +8. **state.md 模式**：复杂（13-15 行），含版本信息和发布状态 + +### 通用增强 + +- `--interactive` 标志：强制对话模式，逐项确认所有自动推断的信息（覆盖零提问行为） +- 判定结果在输出中用一句话交代（不暴露阶段标签） +- 用户可在输出后说"调整一下"进入交互修改 + +### Git 策略检测 + +阶段 B/C 默认执行。从 Git 分支模式推断分支策略： + +``` +git branch -a --list | head -20 +``` + +| 分支模式 | 推断策略 | +|---------|---------| +| 仅 `main`（或 `master`）+ 特性分支 | trunk-based | +| `main` + `develop` + `release/*` + `feature/*` | gitflow | +| `main` + `staging` + `production` | 环境分支 | +| 无法判断 | 询问用户或标注"待定" | + +**写入位置**：context.md 的"开发流程"section。 + +## §2 最小初始化（默认） + +### 生成规则 + +1. **state.md**：使用模板，替换占位符： + - `{{OBJECTIVE}}` → 用户提供或自动检测的一句话描述 + - `{{MOS_SUMMARY}}` → `（待定义）` + - `{{NEXT_ACTION}}` → 按生命周期阶段选择引导语 +2. **project.md**：使用模板，替换 `{{PROJECT_NAME}}` 和 `{{PROJECT_DESCRIPTION}}` + - 阶段 B/C：在价值功能树 section 预填充检测到的 PF 候选 +3. **backlog/**：创建空目录 +4. **rules/workflow.md**：从 Plugin 模板复制 +5. **rules/checks.md**：从项目工具链精准检测生成（见 §9 质量检查引导） +6. **context.md**（按阈值生成）：扫描项目代码库检测技术栈和编码约定： + - 检测 package.json / pyproject.toml / go.mod / Cargo.toml 确定技术栈 + - 检测 .eslintrc / .prettierrc / biome.json / ruff.toml / .editorconfig 提取编码规范 + - 检测 tsconfig.json / Dockerfile / docker-compose.yml 推断架构约束 + - 检测 Makefile / justfile / pnpm-workspace.yaml 识别构建工具和 monorepo + - 从代码文件采样（3-5 个主要文件）提取命名风格和代码模式 + - 仅记录已确认的约定（检测到的），不猜测未发现的 + - 按 context-format.md "50% 猜错"规则，只记录 Claude 可能猜错的约定 + - **阈值**：检测到 ≥ 1 条非显而易见的约定即创建（有一个约定就值得记录） + - **阶段 B/C**：Git 策略检测结果也写入 context.md +7. **CI/CD 自动检测**（静默，无需用户确认）： + - 按 `integrations-format.md` 的"CI 自动检测映射表"扫描项目根目录 + - 检测到 CI 配置文件 → 自动创建 `integrations/config.md`（仅 CI/CD section），来源标记 `auto-detect` + - 检测到的检查命令写入"检查命令"字段 + - 未检测到 CI 配置 → 不创建 integrations/，不提示 +8. **阶段 C 额外生成**：integrations/config.md（版本管理 + 环境）、metrics/dashboard.md（DORA 基线） + +### 同步配置提议 + +检测到 git remote 时，按生命周期阶段调整提议强度： + +1. 检查 `git remote get-url origin` 是否可用 +2. 可用时： + - **阶段 A/B**（可选）：自然语言提议："检测到 GitHub 仓库 {owner}/{repo}，是否要配置外部同步？" + - **阶段 C**（推荐）：措辞调整："已发布项目通常需要外部同步，建议运行 `/pace-sync setup` 配置 CR 与 GitHub Issue 的同步。" + - 用户同意 → 自动执行 `/pace-sync setup` 流程（复用 sync-procedures §2） + - 用户拒绝或忽略 → 静默跳过 +3. 不可用 → 静默跳过 + +**规则**：仅提议，不阻断初始化流程。提议不超过 2 句话。后续可随时通过 `/pace-sync setup` 手动配置。 + +### 跨项目经验导入 + +跨项目经验导入（`--import-insights`）的处理规则见 `init-procedures-from.md` §2。已有 `.devpace/` 的项目也可独立使用此参数（不重新初始化，仅导入经验）。 + +### .gitignore 建议 + +初始化完成后提示： +> "建议在 .gitignore 中添加 `.devpace/`，除非你想版本控制项目状态文件。" + +如果项目根目录已有 `.gitignore` 且未包含 `.devpace/`，询问是否自动添加。 + +## §3 CLAUDE.md 智能合并 + +### 合并策略 + +使用 `` / `` 标记实现幂等注入： + +1. **检测现有 CLAUDE.md**：读取项目根目录 `CLAUDE.md` +2. **搜索标记**：查找 `` 和 `` +3. **按情况处理**： + - **已有标记** → 替换标记区间内的内容（保留标记本身），实现幂等更新 + - **文件存在但无标记** → 在文件末尾追加空行 + `` + devpace section + `` + - **文件不存在** → 创建新文件，内容为 `` + devpace section + `` + +### 模板内容 + +使用 `templates/claude-md-devpace.md` 模板，模板内容已包含 `` 和 `` 标记。替换模板中的占位符（`{{PROJECT_NAME}}`、`{{PROJECT_POSITIONING}}` 等）后注入。 + +### 安全规则 + +- 不修改标记区间外的 CLAUDE.md 内容 +- 标记区间内的内容视为 devpace 管理区域，可覆盖 +- 用户手动编辑标记区间内的内容会在下次 init 时被覆盖（设计如此，CLAUDE.md devpace section 由 devpace 管理） + +## §4 初始化后自动校验 + +初始化完成后自动执行轻量校验： + +1. **文件存在性**：校验所有生成文件存在且非空 +2. **state.md 合规**：校验行数在阶段对应范围内（A: 5-8, B: 10-12, C: 13-15），包含必需 section（目标、当前工作、下一步、版本标记） +3. **project.md 合规**：校验包含项目名和描述，价值功能树 section 存在（可为空桩） +4. **CLAUDE.md 注入**：校验 `` 和 `` 标记存在 +5. **checks.md 最低标准**：至少含 2 条检查项（1 条命令检查 + 1 条意图检查） + +**结果处理**： +- 全部通过 → 输出一行确认："✅ 所有文件校验通过" +- 有问题 → 尝试自动修复（补缺失 section、修复格式），修复后重新校验；无法自动修复则提示用户 + +## §5 情境化引导规则 + +### 按生命周期阶段 + +| 阶段 | 引导语 | 具体 prompt 示例 | +|------|--------|-----------------| +| 阶段 A | "试试说'帮我实现 XXX'，我会自动创建第一个 CR 开始工作" | "帮我实现用户登录功能" | +| 阶段 B | "试试说'帮我修复 XXX'或'帮我添加 XXX'，devpace 会自动追踪变更" | "帮我修复首页加载慢的问题" | +| 阶段 C | "试试说'准备发布 vX.Y.Z'或'线上有个紧急 bug'" | "准备发布 v2.1.0" | + +### 按初始化模式 + +| 模式 | 额外引导 | +|------|---------| +| `--from` | "已从文档生成 N 个产品功能，试试 `/pace-status tree` 查看全景" | +| `full` 业务阶段跳过 | "随时可以 `/pace-retro` 回顾并定义业务目标" | + +### 通用速查 + +初始化完成后始终附加常用命令速查（3-5 条）： + +``` +常用命令： +- 开始工作："帮我实现/修复/添加 XXX" +- 查看进度：/pace-status +- 管理变更：/pace-change +- 回顾总结：/pace-retro +``` + +### git remote 检测 + +检测到 `git remote get-url origin` 返回 GitHub URL → 追加："运行 `/pace-sync setup` 可将 CR 同步到 GitHub Issues。" + +## §6 按需目录创建 + +以下目录和文件在首次使用对应功能时由 Claude 自动创建，不在 init 时预创建： + +| 目录/文件 | 创建时机 | 创建者 | +|-----------|---------|--------| +| `iterations/current.md` | 首次 `/pace-plan` | pace-plan Skill | +| `metrics/dashboard.md` | 首次 `/pace-retro`（阶段 A/B）或 init（阶段 C） | pace-retro Skill / pace-init | +| `metrics/insights.md` | 首次 CR merged 后 pace-learn 执行 | pace-learn（自动） | +| `releases/` | 首次 `/pace-release create` | pace-release Skill | +| `integrations/config.md` | CI 自动检测（最小 init）或 init 阶段 C 或首次配置集成 | pace-init / 手动 | +| `.devpace/context.md` | `/pace-init` 或首次技术约定讨论 | init-procedures / Claude 自动 | + +Claude 在需要写入上述路径时，先检查目录是否存在，不存在则自动创建（mkdir -p 语义），不报错、不提示。 + +## §7 延后收集时机 + +最小初始化时 project.md 为桩状态。以下时机触发内容填充： + +1. **首个 CR 创建时**：Claude 根据用户描述自动推断关联的 PF，在 project.md 的价值功能树中创建初始结构（一个推断的 BR + PF + CR 关联），同时为 PF 行追加括号内用户故事（从用户描述提炼） +2. **首次 `/pace-retro`**：如果 project.md 仍无业务目标，引导用户定义 OBJ 和 MoS +3. **用户主动讨论业务目标时**：Claude 引导定义 OBJ 和 MoS 并回填 project.md +4. **首次 `/pace-change` 时**：如果 project.md 的"范围"section 仍为桩状态，引导用户定义"做什么/不做什么"并回填 +5. **用户主动讨论项目范围时**：Claude 引导定义范围边界并回填 project.md 的"范围"section +6. **技术/产品讨论中明确偏好时**：Claude 将确认的技术或产品决策追加到 project.md 的"项目原则"section（标注来源和日期） +7. **技术约定讨论时**：用户讨论编码规范、技术选型或架构约束时，Claude 将确认的约定追加到 context.md 对应 section + +## §8 迁移框架 + +### 版本检测 + +检查 `state.md` 末尾的 `` 标记： + +- 无标记 → 视为 v1.2.0（标记引入前的版本），触发迁移 +- 标记版本 < 当前版本 → 触发增量迁移 +- 标记版本 = 当前版本 → 不迁移 + +### 增量迁移规范 + +每次版本升级在本章节追加 `vOLD → vNEW` 增量迁移段。迁移前提示用户确认，完成后输出变更摘要。 + +**通用迁移安全规则**： + +- **只添加不删除**：迁移不删除任何现有文件或字段 +- **默认值兼容**：新字段全部可选，不填写时使用默认值 +- **回滚方案**：迁移前自动 `git commit`（如有未提交变更），迁移后可通过 `git revert` 回滚 +- **幂等性**：同一迁移重复执行不产生副作用 + +### v1.2.0 → v1.5.0 迁移 + +**触发条件**：`devpace-version` 为 1.2.0（或缺失标记）。 + +**迁移步骤**： + +1. 通知用户："检测到 v1.2.0 项目，建议升级到 v1.5.0 以支持外部同步、增强的质量门和生命周期感知。" +2. 更新版本标记：`` +3. 更新 rules/workflow.md（从 Plugin 模板覆盖，新增同步相关状态） +4. 输出摘要："升级完成 v1.2.0 → v1.5.0。变更：版本标记更新、工作流规则更新。现有数据无损。" + + + +## §9 质量检查引导 + +根据项目工具链生成 checks.md。检测规则和命令映射表见 `init-procedures-checks.md`（权威源）。 +最小初始化时自动生成不询问；`--full` 模式时引导用户确认和补充。 +生成的 checks.md 须符合 `knowledge/_schema/checks-format.md` 格式契约。 + +## §10 Monorepo 感知初始化 + +### 信号检测 + +| 文件 | Monorepo 工具 | +|------|-------------| +| `pnpm-workspace.yaml` | pnpm workspace | +| `nx.json` | Nx | +| `turbo.json` | Turborepo | +| `lerna.json` | Lerna | +| `rush.json` | Rush | + +### 组织方式选择 + +检测到 monorepo 信号时，使用 AskUserQuestion 询问组织方式： + +**A) 根目录单一 .devpace/（推荐小型 monorepo，<5 个子包）**： +- 标准初始化流程 +- context.md 记录 monorepo 结构和子包列表 +- PF 树按子包组织 + +**B) 根共享 + 子包独立追踪（大型 monorepo，≥5 个子包）**： +- 根 `.devpace/`：rules/（共享规则）+ context.md（全局约定） +- 子包 `.devpace/`：state.md + project.md + backlog/（独立追踪） +- 子包的 rules/ 继承根目录（不重复创建） + +### 子包发现 + +- 从 monorepo 配置文件读取 workspace 列表 +- 验证子包目录存在 +- 为每个子包生成独立的 state.md 和 project.md diff --git a/skills/pace-init/init-procedures-dryrun.md b/skills/pace-init/init-procedures-dryrun.md new file mode 100644 index 0000000..05838d6 --- /dev/null +++ b/skills/pace-init/init-procedures-dryrun.md @@ -0,0 +1,40 @@ +# dry-run 规程 + +> **职责**：`/pace-init --dry-run` 的详细执行规则。 + +## 触发 + +`/pace-init --dry-run [其他参数]` + +## 行为 + +执行完整的检测和规划逻辑（生命周期检测、工具链检测、信息收集等），但不写入任何文件。 + +## 输出格式 + +``` +/pace-init 预览（dry-run 模式，不写入文件）： + +检测结果： +- 项目阶段：[阶段描述] +- 项目名称：[名称]（来源：[package.json/目录名/...]） +- 项目描述：[描述]（来源：[...]） +- 技术栈：[语言] + [框架] +- 工具链：[测试/lint/typecheck 工具] + +将创建的文件： +.devpace/ +├── state.md — 项目状态追踪（[N] 行） +├── project.md — 项目定义和价值功能树 +├── backlog/ — CR 存放目录 +├── rules/ +│ ├── workflow.md — 工作流规则 +│ └── checks.md — 质量检查（[M] 条检查项） +├── context.md — 技术约定（[K] 条约定） +└── integrations/ + └── config.md — 集成配置（CI/CD + 版本管理） + +CLAUDE.md — 将注入 devpace 研发协作 section + +确认初始化？运行 `/pace-init [项目名称]` 开始。 +``` diff --git a/skills/pace-init/init-procedures-from.md b/skills/pace-init/init-procedures-from.md new file mode 100644 index 0000000..0e58667 --- /dev/null +++ b/skills/pace-init/init-procedures-from.md @@ -0,0 +1,53 @@ +# --from / --import-insights 规程 + +> **职责**：`/pace-init --from` 文档驱动初始化和 `--import-insights` 跨项目经验导入的详细执行规则。核心初始化规则见 `init-procedures-core.md`。 + +## §1 --from 模式增强解析 + +### 路径处理 + +- **单文件**：`/pace-init --from prd.md` → 直接读取 +- **目录路径**：`/pace-init --from requirements/` → 扫描目录下所有 .md/.txt 文件，综合提取 +- **多文件**：`/pace-init --from prd.md --from api-spec.md` → 依次读取，合并提取结果 + +### 解析规则 + +| 文档元素 | 映射目标 | 解析方法 | +|---------|---------|---------| +| 用户故事（As a... I want... So that...） | BR（业务需求） | 模式匹配 + 语义分析 | +| 功能列表 / Features section | PF（产品功能）树 | 层级提取 | +| API 端点列表 / OpenAPI paths | PF（按资源分组） | 结构化解析（YAML/JSON） | +| 技术需求 / Non-functional requirements | project.md "项目原则" | 语义分类 | +| 优先级标记（P0/P1/Must/Should） | CR 优先级候选 | 标签提取 | +| 时间线 / Milestones | 迭代规划候选 | 时间点提取 | + +### 确认流程 + +1. 解析完成后展示提取结果的结构化摘要 +2. 用 AskUserQuestion 让用户确认或调整 +3. 确认后写入 project.md +4. 目录路径解析时，若文件过多（>10），先输出文件列表让用户筛选 + +### API 规格特殊处理 + +检测到 OpenAPI/Swagger 文件（.yaml/.json 含 `openapi` 或 `swagger` 关键词）： +- 提取 paths → 按资源（/users、/orders 等）分组为 PF +- 提取 tags → 作为 PF 分组名称 +- 提取 descriptions → 作为 PF 描述 + +## §2 跨项目经验导入（--import-insights） + +当用户执行 `/pace-init --import-insights <路径>` 时，在初始化完成后执行经验导入： + +1. 读取指定路径的导出文件 +2. 校验格式（应符合 insights-format.md 导出文件格式） +3. 按导入规则处理每个条目： + - 跳过偏好（preference）类型条目 + - 置信度 × 0.8 降级 + - 验证次数重置为 0 + - 追加"导入日期"字段 +4. 与已有 insights.md 去重（同标题保留高置信度版本） +5. 写入 `.devpace/metrics/insights.md`（目录不存在则创建） +6. 输出摘要：`"已导入 N 条经验（来自 [项目名]），置信度已降级（×0.8），需在本项目中重新验证。跳过 M 条偏好类型条目。"` + +已有 `.devpace/` 的项目也可独立使用此参数（不重新初始化，仅导入经验）。 diff --git a/skills/pace-init/init-procedures-full.md b/skills/pace-init/init-procedures-full.md new file mode 100644 index 0000000..1bf7422 --- /dev/null +++ b/skills/pace-init/init-procedures-full.md @@ -0,0 +1,154 @@ +# full 模式增强规程 + +> **职责**：`/pace-init full` 专用规程。覆盖环境探测、分阶段引导和发布配置收集。核心初始化规则见 `init-procedures-core.md`。 + +## §1 环境探测 + +当 `/pace-init full` 执行时，在信息收集和生成目录之间，自动执行环境探测。探测结果用于预填 `context.md` 和 `integrations/config.md`，减少用户手动配置。 + +### 探测步骤 + +#### 1. 项目类型检测 + +扫描项目根目录的配置文件，识别技术栈和项目架构： + +| 探测文件 | 推断信息 | 写入位置 | +|---------|---------|---------| +| `package.json` | 语言=JS/TS + 框架（react/vue/angular/next/express 从 dependencies 推断） | context.md 技术栈 | +| `pyproject.toml` / `setup.py` | 语言=Python + 框架（django/flask/fastapi 从依赖推断） | context.md 技术栈 | +| `go.mod` | 语言=Go + module 名 | context.md 技术栈 | +| `Cargo.toml` | 语言=Rust | context.md 技术栈 | +| `tsconfig.json` | TypeScript 启用 + strict 模式等配置 | context.md 技术栈 | +| `Dockerfile` / `docker-compose.yml` | 容器化部署 | context.md 架构约束 | +| `Makefile` / `justfile` | 构建系统 | context.md 构建工具 | + +多技术栈项目（monorepo 等）→ 全部记录。无可识别配置文件 → 标注"待定"。 + +#### 2. MCP 感知 + +检查 Claude Code 环境中已可用的 MCP Server，预填集成建议： + +| 检查路径 | 推断信息 | 写入位置 | +|---------|---------|---------| +| `.mcp.json`（项目级） | 已配置的 MCP Server 列表 | integrations/config.md MCP section | +| 全局 MCP 配置（Claude Code 用户设置） | 全局可用的 MCP Server | integrations/config.md MCP section | + +**预填逻辑**： +- 检测到 Playwright MCP → 标注"可用于 E2E 测试和浏览器验收" +- 检测到 Tavily MCP → 标注"可用于研究和文档查询" +- 无 MCP 配置 → 跳过此 section + +#### 3. CI/CD 检测 + +按 `knowledge/_schema/integrations-format.md` "CI 自动检测映射表"扫描项目 CI/CD 配置。full 模式额外提取深度信息： + +| CI 工具 | 额外推断 | +|---------|---------| +| GitHub Actions | 工作流名称、触发事件（push/PR/tag） | +| GitLab CI | 阶段定义 | +| 其他 | Pipeline/配置存在性 | + +额外检测部署平台（非 CI 工具）： + +| 探测文件 | 部署平台 | +|---------|---------| +| `vercel.json` / `.vercel/` | Vercel | +| `netlify.toml` | Netlify | + +**预填逻辑**：提取工具名称和触发方式 → 写入 integrations/config.md CI/CD section。无 CI/CD 配置 → 跳过。 + +#### 4. Git 策略检测 + +按 `init-procedures-core.md` "Git 策略检测"规则执行。full 模式下探测结果在 §1 探测摘要中展示给用户确认。 + +### 探测输出 + +探测完成后，输出探测摘要给用户确认： + +``` +环境探测完成： +- 技术栈：[语言] + [框架]（从 [配置文件] 检测） +- CI/CD：[工具名]（[触发方式]） +- 分支策略：[策略名] +- MCP：[N] 个可用 Server +以上信息已预填到 context.md 和 integrations/config.md，你可以修改或补充。 +``` + +### 探测安全规则 + +- **只检测不猜测**：仅记录从配置文件中确认的信息，不推测缺失的配置 +- **不执行命令**：除 `git branch` 外不执行项目的构建/测试命令 +- **用户确认**：探测结果在完整初始化流程中展示给用户确认，不自动写入 +- **最小初始化不触发**：环境探测仅在 `--full` 模式中执行（但 Git 策略检测在阶段 B/C 默认执行） + +## §2 分阶段引导 + +### 阶段 1：基础（必须） + +执行生命周期检测 + 信息收集 + 生成 .devpace/（同最小初始化 + 环境探测）。完成后立即可用。 + +### 阶段 2：业务（可选） + +使用 AskUserQuestion 询问："要现在定义业务目标和成效指标吗？可稍后 /pace-retro 补充。" + +用户选择"现在定义"→ 引导收集： +1. 业务目标（OBJ）：项目的核心价值和成功标准 +2. 成效指标（MoS）：可衡量的指标列表 +3. 业务需求（BR）：高层需求分解 + +用户选择"稍后再说"→ 跳过，project.md 保持桩状态。 + +### 阶段 3：发布配置（可选） + +使用 AskUserQuestion 询问："检测到 [CI 工具]，要配置发布流程吗？可稍后编辑 integrations/config.md。" + +用户选择"现在配置"→ 引导收集发布配置（见 §3 发布配置收集）。 +用户选择"稍后再说"→ 跳过。 + +### 阶段 4：外部同步（可选） + +使用 AskUserQuestion 询问："检测到 GitHub 仓库，要配置外部同步吗？可稍后 /pace-sync setup。" + +用户选择"现在配置"→ 执行 `/pace-sync setup`。 +用户选择"稍后再说"→ 跳过。 + +### 提前退出 + +用户在任何阶段可说"够了"→ 跳过剩余阶段，使用已收集的信息完成初始化。 + +## §3 发布配置收集 + +### 有发布流程时 + +额外收集信息： +1. **环境列表**：如 staging、production（写入 `integrations/config.md`） +2. **CI/CD 工具**（可选）：如 GitHub Actions、Jenkins、GitLab CI +3. **发布审批**：自动（CI 通过即部署）/ 手动确认（需人类审批） + +生成 `.devpace/integrations/config.md`： + +```markdown +# 集成配置 + +## 环境 + +| 环境 | 用途 | URL | +|------|------|-----| +| staging | 预发布验证 | [URL] | +| production | 正式环境 | [URL] | + +## CI/CD + +- **工具**：[工具名称] +- **触发方式**：[push/manual/tag] + +## 发布审批 + +- **模式**：[auto/manual] +``` + +### 无发布流程时 + +- 跳过发布配置 +- `releases/` 和 `integrations/` 目录不创建（按需创建策略） +- 相关功能（/pace-release、/pace-feedback 的 Release 追溯）降级 diff --git a/skills/pace-init/init-procedures-reset.md b/skills/pace-init/init-procedures-reset.md new file mode 100644 index 0000000..ec83717 --- /dev/null +++ b/skills/pace-init/init-procedures-reset.md @@ -0,0 +1,31 @@ +# 重置规程 + +> **职责**：`/pace-init --reset [--keep-insights]` 的详细执行规则。 + +## 触发 + +`/pace-init --reset [--keep-insights]` + +## 流程 + +1. **前置检查**：确认 `.devpace/` 存在 +2. **外部关联检测**： + - 检查 `.devpace/integrations/sync-mapping.md` 是否存在 + - 存在 → 提示："发现外部同步映射，关联的 GitHub Issues 需手动处理。" +3. **二次确认**：使用 AskUserQuestion 确认："即将删除 .devpace/ 及所有追踪数据（N 个 CR、M 个迭代记录），此操作不可逆。确认删除？" +4. **保留 insights**（如 `--keep-insights`）： + - 备份 `.devpace/metrics/insights.md` 到临时位置 +5. **删除 .devpace/**：删除整个目录 +6. **清理 CLAUDE.md**： + - 读取 CLAUDE.md，删除 `` 到 `` 之间的内容（含标记本身） + - 清理可能遗留的多余空行 +7. **恢复 insights**（如 `--keep-insights`）： + - 创建 `.devpace/metrics/` 目录 + - 将备份的 insights.md 恢复 +8. **完成提示**："已清除 .devpace/。可运行 /pace-init 重新初始化。" + +## 安全规则 + +- 必须二次确认，不可静默删除 +- 不删除 .devpace/ 以外的文件（除 CLAUDE.md devpace section 外） +- `--keep-insights` 保留经验数据（经验是跨项目资产） diff --git a/skills/pace-init/init-procedures-template.md b/skills/pace-init/init-procedures-template.md new file mode 100644 index 0000000..b16c395 --- /dev/null +++ b/skills/pace-init/init-procedures-template.md @@ -0,0 +1,25 @@ +# 模板导出与应用规程 + +> **职责**：`/pace-init --export-template` 和 `--from-template` 的详细执行规则。 + +## 导出（--export-template） + +**前置条件**：`.devpace/` 目录存在。 + +**导出内容**（创建 `.devpace-template/` 目录）： + +| 源文件 | 导出处理 | +|--------|---------| +| rules/workflow.md | 直接复制 | +| rules/checks.md | 移除项目特定的 bash 命令路径，保留结构和意图检查 | +| context.md | 移除项目特定的路径和名称，保留通用约定 | +| integrations/config.md | 移除项目特定的 URL 和密钥，保留结构 | + +**输出**：`".devpace-template/ 已创建，包含 N 个模板文件。新项目可使用 /pace-init --from-template .devpace-template/ 应用。"` + +## 应用（--from-template） + +1. 读取模板目录中的文件 +2. 执行正常初始化流程（生命周期检测 + 信息收集） +3. 用模板文件覆盖默认模板（workflow.md、checks.md、context.md、integrations/config.md） +4. 继续正常流程（替换占位符、生成 state.md/project.md） diff --git a/skills/pace-init/init-procedures-verify.md b/skills/pace-init/init-procedures-verify.md new file mode 100644 index 0000000..bc91139 --- /dev/null +++ b/skills/pace-init/init-procedures-verify.md @@ -0,0 +1,54 @@ +# 健康检查规程 + +> **职责**：`/pace-init --verify [--fix]` 的详细执行规则。 + +## 触发 + +`/pace-init --verify [--fix]` + +## 前置条件 + +检查 `.devpace/` 目录存在，不存在则提示"未找到 .devpace/ 目录，请先运行 /pace-init"。 + +## 校验清单 + +遍历 `.devpace/` 所有文件，按对应 Schema 逐一校验： + +| 文件 | Schema | 校验内容 | +|------|--------|---------| +| state.md | state-format.md | 必需 section、版本标记 | +| project.md | project-format.md | 项目名、价值功能树 section | +| rules/workflow.md | — | 文件存在且非空 | +| rules/checks.md | checks-format.md | Gate section 存在、至少 2 条检查 | +| context.md | context-format.md | section 结构合规 | +| backlog/CR-*.md | cr-format.md | 必填字段存在 | +| iterations/*.md | iteration-format.md | section 结构合规 | +| releases/*.md | release-format.md | section 结构合规 | +| integrations/config.md | integrations-format.md | section 结构合规 | +| metrics/dashboard.md | — | 文件存在且非空 | +| metrics/insights.md | insights-format.md | 条目格式合规 | +| CLAUDE.md | — | devpace section 标记存在 | + +## 输出格式 + +``` +.devpace/ 健康检查报告： +✅ state.md — 正常 +✅ project.md — 正常 +⚠️ rules/checks.md — 缺少 Gate 2 section（可自动修复） +❌ backlog/CR-001.md — 缺少"意图"字段（需人工处理） +✅ CLAUDE.md — devpace section 存在 + +总计：N 个文件，M 正常，X 可修复，Y 需人工 +``` + +## --fix 行为 + +当指定 `--fix` 时，自动修复可修复项： + +- 缺失的 section → 补充空 section 模板 +- 缺失的版本标记 → 补充当前版本标记 +- 格式问题（多余空行、缺失分隔符）→ 规范化 +- **不修改语义内容**（不改用户写的文本、不删除用户数据） + +修复后重新输出报告。 diff --git a/skills/pace-init/init-procedures.md b/skills/pace-init/init-procedures.md deleted file mode 100644 index 58718b4..0000000 --- a/skills/pace-init/init-procedures.md +++ /dev/null @@ -1,282 +0,0 @@ -# 初始化执行规程 - -> **职责**：初始化和迁移的详细执行规则。/pace-init 触发后，Claude 按需读取本文件。 - -## §0 速查卡片 - -- **最小初始化（默认）**：生成 state.md/project.md/backlog/rules + CI/CD 自动检测 -- **按需目录创建**：iterations/releases/insights 等目录在首次使用时创建 -- **延后收集时机**：功能规格/架构约束等在具体工作阶段按需采集 -- **v0.1→v0.9 迁移流程**：旧版 .devpace 结构的自动检测和迁移 -- **环境探测（--full 模式）**：完整项目扫描——技术栈/架构/CI/CD/发布配置 -- **质量检查引导**：按项目类型生成 checks.md（检查命令+阈值） - -## 最小初始化（默认） - -### 生成规则 - -1. **state.md**：使用模板，替换占位符： - - `{{OBJECTIVE}}` → 用户提供的一句话描述 - - `{{MOS_SUMMARY}}` → `（待定义）` - - `{{NEXT_ACTION}}` → `说"帮我实现 X"开始第一个功能。` -2. **project.md**：使用模板，替换 `{{PROJECT_NAME}}` 和 `{{PROJECT_DESCRIPTION}}` -3. **backlog/**：创建空目录 -4. **rules/workflow.md**：从 Plugin 模板复制 -5. **rules/checks.md**：从项目类型自动检测生成（见"质量检查引导"章节） -6. **context.md**（可选自动生成）：扫描项目代码库检测技术栈和编码约定： - - 检测 package.json / pyproject.toml / go.mod / Cargo.toml 确定技术栈 - - 检测 .eslintrc / .prettierrc / ruff.toml / .editorconfig 提取编码规范 - - 检测 tsconfig.json / Dockerfile / docker-compose.yml 推断架构约束 - - 从代码文件采样（3-5 个主要文件）提取命名风格和代码模式 - - 仅记录已确认的约定（检测到的），不猜测未发现的 - - 如果检测到的约定 < 3 条，跳过 context.md 创建（信息量不足） - -7. **CI/CD 自动检测**（静默，无需用户确认）： - - 按 `integrations-format.md` 的"CI 自动检测映射表"扫描项目根目录 - - 检测到 CI 配置文件 → 自动创建 `integrations/config.md`（仅 CI/CD section），来源标记 `auto-detect` - - 检测到的检查命令写入"检查命令"字段 - - 未检测到 CI 配置 → 不创建 integrations/，不提示（核心流程不受影响） - - 与"环境探测（--full 模式）"的 CI 检测互补：最小初始化只检测 CI 工具和检查命令，--full 模式额外检测触发方式和工作流详情 - -### 跨项目经验导入（--import-insights） - -当用户执行 `/pace-init --import-insights <路径>` 时，在初始化完成后（Step 7 CI 检测之后）执行经验导入： - -1. 读取指定路径的导出文件 -2. 校验格式（应符合 insights-format.md 导出文件格式） -3. 按导入规则处理每个条目： - - 跳过偏好（preference）类型条目 - - 置信度 × 0.8 降级 - - 验证次数重置为 0 - - 追加"导入日期"字段 -4. 与已有 insights.md 去重（同标题保留高置信度版本） -5. 写入 `.devpace/metrics/insights.md`（目录不存在则创建） -6. 输出摘要：`"已导入 N 条经验（来自 [项目名]），置信度已降级（×0.8），需在本项目中重新验证。跳过 M 条偏好类型条目。"` - -已有 .devpace/ 的项目也可独立使用此参数（不重新初始化，仅导入经验）。 - -### .gitignore 建议 - -初始化完成后提示： -> "建议在 .gitignore 中添加 `.devpace/`，除非你想版本控制项目状态文件。" - -如果项目根目录已有 `.gitignore` 且未包含 `.devpace/`，询问是否自动添加。 - -## 按需目录创建 - -以下目录和文件在首次使用对应功能时由 Claude 自动创建，不在 init 时预创建： - -| 目录/文件 | 创建时机 | 创建者 | -|-----------|---------|--------| -| `iterations/current.md` | 首次 `/pace-plan` | pace-plan Skill | -| `metrics/dashboard.md` | 首次 `/pace-retro` | pace-retro Skill | -| `metrics/insights.md` | 首次 CR merged 后 pace-learn 执行 | pace-learn（自动） | -| `releases/` | 首次 `/pace-release create` | pace-release Skill | -| `integrations/config.md` | CI 自动检测（最小 init）或首次配置集成 | pace-init（auto-detect）/ pace-init full / 手动 | -| `.devpace/context.md` | `/pace-init` 或首次技术约定讨论 | init-procedures / Claude 自动 | - -Claude 在需要写入上述路径时，先检查目录是否存在，不存在则自动创建（mkdir -p 语义），不报错、不提示。 - -## 延后收集时机 - -最小初始化时 project.md 为桩状态。以下时机触发内容填充： - -1. **首个 CR 创建时**：Claude 根据用户描述自动推断关联的 PF，在 project.md 的价值功能树中创建初始结构（一个推断的 BR + PF + CR 关联），同时为 PF 行追加括号内用户故事（从用户描述提炼） -2. **首次 `/pace-retro`**：如果 project.md 仍无业务目标，引导用户定义 OBJ 和 MoS -3. **用户主动讨论业务目标时**：Claude 引导定义 OBJ 和 MoS 并回填 project.md -4. **首次 `/pace-change` 时**：如果 project.md 的"范围"section 仍为桩状态，引导用户定义"做什么/不做什么"并回填 -5. **用户主动讨论项目范围时**：Claude 引导定义范围边界并回填 project.md 的"范围"section -6. **技术/产品讨论中明确偏好时**：Claude 将确认的技术或产品决策追加到 project.md 的"项目原则"section（标注来源和日期） -7. **技术约定讨论时**：用户讨论编码规范、技术选型或架构约束时，Claude 将确认的约定追加到 context.md 对应 section - -## v0.1→v0.9 迁移流程 - -当检测到 `.devpace/state.md` 存在但 `devpace-version` 为 0.1.0 或缺失时触发。 - -### 迁移步骤 - -1. **通知用户**："检测到 v0.1.0 项目，建议升级到 v0.9.0 以支持发布管理、缺陷追踪、角色意识、质量增强和技术约定管理。" -2. **创建新目录**（如不存在）： - - `.devpace/releases/` - - `.devpace/integrations/` -3. **现有 CR 兼容处理**（不修改用户已有内容）： - - 无 `类型` 字段的 CR → 视为 `feature`（不写入，读取时默认） - - 无 `严重度` 字段的 CR → feature 类型不需要，跳过 - - 无 `复杂度`/`执行计划`/`关联`/`checkpoint` 字段 → 全部可选，读取时跳过 -4. **更新版本标记**：`state.md` 末尾 `` -5. **添加教学标记**（如缺失）：`state.md` 末尾 ``（空值，表示全部未教） -6. **更新工作流**：从 Plugin 模板覆盖 `.devpace/rules/workflow.md`（新增 released 状态和 hotfix 路径） -7. **自动扫描 context.md**（可选）：按最小初始化的 context.md 生成规则扫描项目，检测到 ≥3 条约定时自动创建 `.devpace/context.md` -8. **询问发布配置**（Step 2.5） -9. **输出迁移摘要**："升级完成 v0.1.0 → v0.9.0。新增：releases/、integrations/ 目录，教学标记，工作流更新。现有数据无损。" - -### 迁移安全规则 - -- **只添加不删除**：迁移不删除任何现有文件或字段 -- **默认值兼容**：新字段全部可选，不填写时使用默认值 -- **workflow.md 覆盖确认**：覆盖前告知用户变更内容（新增 released 和 hotfix 路径） -- **回滚方案**：迁移前自动 `git commit`（如有未提交变更），迁移后可通过 `git revert` 回滚 -- **跨版本安全**：v0.1.0→v0.9.0 是一次性跳跃迁移，不需要逐版本升级；所有中间版本新增的字段均为可选 - -## 环境探测（`--full` 模式增强） - -当 `/pace-init full` 执行时，在信息收集（Step 1）和生成目录（Step 2）之间，自动执行环境探测。探测结果用于预填 `context.md` 和 `integrations/config.md`，减少用户手动配置。 - -### 探测步骤 - -#### 1. 项目类型检测 - -扫描项目根目录的配置文件，识别技术栈和项目架构： - -| 探测文件 | 推断信息 | 写入位置 | -|---------|---------|---------| -| `package.json` | 语言=JS/TS + 框架（react/vue/angular/next/express 从 dependencies 推断） | context.md 技术栈 | -| `pyproject.toml` / `setup.py` | 语言=Python + 框架（django/flask/fastapi 从依赖推断） | context.md 技术栈 | -| `go.mod` | 语言=Go + module 名 | context.md 技术栈 | -| `Cargo.toml` | 语言=Rust | context.md 技术栈 | -| `tsconfig.json` | TypeScript 启用 + strict 模式等配置 | context.md 技术栈 | -| `Dockerfile` / `docker-compose.yml` | 容器化部署 | context.md 架构约束 | -| `Makefile` | 构建系统=Make | context.md 构建工具 | - -多技术栈项目（monorepo 等）→ 全部记录。无可识别配置文件 → 标注"待定"。 - -#### 2. MCP 感知 - -检查 Claude Code 环境中已可用的 MCP Server，预填集成建议： - -| 检查路径 | 推断信息 | 写入位置 | -|---------|---------|---------| -| `.mcp.json`（项目级） | 已配置的 MCP Server 列表 | integrations/config.md MCP section | -| 全局 MCP 配置（Claude Code 用户设置） | 全局可用的 MCP Server | integrations/config.md MCP section | - -**预填逻辑**： -- 检测到 Playwright MCP → 标注"可用于 E2E 测试和浏览器验收" -- 检测到 Tavily MCP → 标注"可用于研究和文档查询" -- 无 MCP 配置 → 跳过此 section - -#### 3. CI/CD 检测 - -扫描项目中的 CI/CD 配置文件，自动识别部署流水线： - -| 探测文件/目录 | CI/CD 工具 | 推断信息 | -|-------------|-----------|---------| -| `.github/workflows/*.yml` | GitHub Actions | 工作流名称、触发事件（push/PR/tag） | -| `.gitlab-ci.yml` | GitLab CI | 阶段定义 | -| `Jenkinsfile` | Jenkins | Pipeline 存在 | -| `.circleci/config.yml` | CircleCI | 配置存在 | -| `bitbucket-pipelines.yml` | Bitbucket Pipelines | 配置存在 | -| `vercel.json` / `.vercel/` | Vercel | 部署平台=Vercel | -| `netlify.toml` | Netlify | 部署平台=Netlify | - -**预填逻辑**：提取工具名称和触发方式 → 写入 `integrations/config.md` CI/CD section。无 CI/CD 配置 → 跳过。 - -#### 4. Git 策略检测 - -从 Git 分支模式推断分支策略： - -``` -git branch -a --list | head -20 -``` - -| 分支模式 | 推断策略 | -|---------|---------| -| 仅 `main`（或 `master`）+ 特性分支 | trunk-based | -| `main` + `develop` + `release/*` + `feature/*` | gitflow | -| `main` + `staging` + `production` | 环境分支 | -| 无法判断 | 询问用户或标注"待定" | - -**写入位置**：context.md 的"开发流程"section。 - -### 探测输出 - -探测完成后，输出探测摘要给用户确认： - -``` -环境探测完成： -- 技术栈：[语言] + [框架]（从 [配置文件] 检测） -- CI/CD：[工具名]（[触发方式]） -- 分支策略：[策略名] -- MCP：[N] 个可用 Server -以上信息已预填到 context.md 和 integrations/config.md，你可以修改或补充。 -``` - -### 探测安全规则 - -- **只检测不猜测**：仅记录从配置文件中确认的信息，不推测缺失的配置 -- **不执行命令**：除 `git branch` 外不执行项目的构建/测试命令 -- **用户确认**：探测结果在完整初始化流程中展示给用户确认，不自动写入 -- **最小初始化不触发**：环境探测仅在 `--full` 模式中执行，最小初始化中技术栈检测由生成规则第 6 条（context.md 可选生成）覆盖 - -## 发布配置收集 - -### 有发布流程时 - -额外收集信息： -1. **环境列表**：如 staging、production（写入 `integrations/config.md`） -2. **CI/CD 工具**（可选）：如 GitHub Actions、Jenkins、GitLab CI -3. **发布审批**：自动（CI 通过即部署）/ 手动确认（需人类审批） - -生成 `.devpace/integrations/config.md`： - -```markdown -# 集成配置 - -## 环境 - -| 环境 | 用途 | URL | -|------|------|-----| -| staging | 预发布验证 | [URL] | -| production | 正式环境 | [URL] | - -## CI/CD - -- **工具**：[工具名称] -- **触发方式**：[push/manual/tag] - -## 发布审批 - -- **模式**：[auto/manual] -``` - -### 无发布流程时 - -- 跳过发布配置 -- `releases/` 和 `integrations/` 目录不创建（按需创建策略） -- 相关功能（/pace-release、/pace-feedback 的 Release 追溯）降级 - -## 质量检查引导 - -### 默认检查项建议 - -根据项目类型自动建议，包括命令检查和意图检查两种方式： - -| 项目类型 | 检测方式 | 命令检查建议 | 意图检查建议 | 安全检查建议 | -|---------|---------|-------------|-------------|-------------| -| Node.js | package.json 存在 | `npm test`、`npm run lint`、`npm run typecheck` | "所有导出函数有 JSDoc" | `npm audit --audit-level=high` | -| Python | pyproject.toml 或 setup.py | `pytest`、`ruff check`、`mypy` | "所有公共函数有 docstring" | `bandit -r src/` | -| Go | go.mod 存在 | `go test ./...`、`golangci-lint run` | "所有导出函数有注释" | `gosec ./...` | -| 通用 | 其他 | 询问用户自定义 | "单个函数不超过 50 行" | Claude 检查"代码中不含硬编码密钥" | - -最小初始化时自动检测项目类型并生成 checks.md（包含命令检查和至少 1 条意图检查建议），不询问用户。安全检查为推荐项，生成 checks.md 时作为注释包含（``），用户可取消注释启用。完整初始化（`full`）时引导用户确认和补充（含安全检查项）。 - -### 检查项格式 - -checks.md 支持两种检查类型（格式定义见 `knowledge/_schema/checks-format.md`）： - -- **命令检查**：`检查方式：[bash 命令]`——exit code 判定（0=通过） -- **意图检查**：`检查方式：Claude 检查 [自然语言规则]`——Claude 阅读变更代码对照规则判定 - -```markdown -## 质量检查 - -### Gate 1：代码质量（developing → verifying） -- [ ] [检查名称]：`[命令]` -- [ ] [检查名称]：Claude 检查 [自然语言规则] - -### Gate 2：集成验证（verifying → in_review） -- [ ] [检查名称]：`[命令]` -- [ ] [检查名称]：Claude 检查 [自然语言规则] - -### Gate 3：人类审批（in_review → approved） -- [ ] 人类审批：Code Review 通过 -``` diff --git a/skills/pace-init/templates/claude-md-devpace.md b/skills/pace-init/templates/claude-md-devpace.md index 58eb834..23fbb71 100644 --- a/skills/pace-init/templates/claude-md-devpace.md +++ b/skills/pace-init/templates/claude-md-devpace.md @@ -1,3 +1,4 @@ + # {{PROJECT_NAME}} > {{PROJECT_POSITIONING}} @@ -21,3 +22,4 @@ ## 业务目标 {{OBJECTIVES_AND_MOS}} + diff --git a/skills/pace-pulse/pulse-procedures.md b/skills/pace-pulse/pulse-procedures.md index 104e706..5ed3dd6 100644 --- a/skills/pace-pulse/pulse-procedures.md +++ b/skills/pace-pulse/pulse-procedures.md @@ -14,6 +14,7 @@ | 迭代频繁变更 | current.md 变更记录条数 | > 3 条 | | 上下文密集 | 本会话已有 3+ 个 Gate 1 通过事件 | ≥ 3 个 | | 风险积压 | `.devpace/risks/` 中 open 状态风险 > 3 或 High 严重度风险 > 0 | Medium | +| 同步滞后 | sync-mapping.md 存在时，已关联 CR 最后同步距今时间 | > 24h | ## 建议模板 @@ -34,6 +35,7 @@ | 迭代频繁变更 | "本迭代已有 N 次范围变更，注意目标偏移风险。" | | 上下文密集 | "本次会话上下文较重（N 个变更实现），建议在逻辑边界 /compact。" | | 风险积压 | "有 [N] 个未处理风险（含 [M] 个高级别），建议运行 `/pace-guard report` 查看详情。" | +| 同步滞后 | "有 N 个 CR 的外部同步已超过 24 小时，建议运行 `/pace-sync push` 更新。" | ## 输出规则 @@ -62,6 +64,7 @@ | 5 | defect 占比 > 30% | "关注质量改进" | | 6 | MoS 达成率 > 80% | "回顾业务目标" | | 7 | 风险积压（`.devpace/risks/` 存在且 open 风险 > 3 或 High > 0） | "有 [N] 个未处理风险需关注。" | +| 8 | sync-mapping.md 存在 + 关联 CR 最后同步 > 24h | "有 N 个 CR 外部同步已滞后" | ### 与推进模式脉搏检查的关系 diff --git a/skills/pace-status/status-procedures.md b/skills/pace-status/status-procedures.md index 4301122..6840524 100644 --- a/skills/pace-status/status-procedures.md +++ b/skills/pace-status/status-procedures.md @@ -43,6 +43,28 @@ - 与 §1 节奏提醒互补：§1 是会话开始的一次性提醒，建议下一步是 /pace-status 的持久特性 - 如果 §1 已给出相同建议（如 in_review 积压），/pace-status 不重复 +### 同步状态摘要（sync-mapping.md 存在时） + +当 `.devpace/integrations/sync-mapping.md` 存在时，概览末尾追加 1 行同步摘要。不存在时静默跳过。 + +**数据采集**： +1. 读取 sync-mapping.md 关联记录表 +2. 对每个关联 CR：比较 devpace 状态与最后同步时间 +3. 统计：已同步数（最后同步时间 ≥ 最近状态变更时间）、待推送数（反之） + +**输出格式**： +``` +[进度条输出] +💡 建议：[建议内容] +🔗 同步：{N} 个 CR 已同步，{M} 个待推送 +``` + +**规则**： +- 同步行不计入主输出 ≤3 行限制（与建议行同级，作为附加信息） +- 全部已同步 → `🔗 同步：{N} 个 CR 已同步`（省略待推送数） +- 无关联 CR → 不显示同步行 +- 无法判断一致性（如 gh 不可用）→ `🔗 同步：{N} 个 CR 已关联（状态未检查）` + ## detail：功能树缩进可视化 **输出格式示例**： diff --git a/skills/pace-sync/SKILL.md b/skills/pace-sync/SKILL.md new file mode 100644 index 0000000..c35cdc4 --- /dev/null +++ b/skills/pace-sync/SKILL.md @@ -0,0 +1,73 @@ +--- +description: "Use when user wants to sync devpace state with external tools (GitHub/Linear/Jira), says '同步/sync/push/pull/关联 Issue/配置同步/setup/解除关联/unlink/创建 Issue/create/同步状态/status', or /pace-sync. NOT for internal devpace state changes (use /pace-dev) or release operations (use /pace-release)" +argument-hint: "[子命令] [参数]" +allowed-tools: Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion +model: sonnet +--- + +# /pace-sync — 外部工具同步 + +将 devpace 研发状态与外部项目管理工具（GitHub/Linear/Jira/GitLab）双向桥接。 + +## 与现有机制的关系 + +- /pace-dev 管理 CR 内部状态转换 → /pace-sync 将状态变化推送到外部 +- /pace-change 管理变更操作 → /pace-sync 同步变更后状态到外部 +- /pace-release 管理发布流程 → /pace-sync 同步发布状态到外部（Phase 19） +- /pace-review Gate 2 结果 → /pace-sync 同步为外部 PR Review（Phase 19） +- /pace-status 展示内部状态 → /pace-sync status 展示同步状态和外部链接 + +## 推荐使用流程 + +首次配置：`setup` → 关联：`link` → 日常：`push` / `status` + +## 输入 + +`$ARGUMENTS` 解析为子命令 + 参数。 + +### 子命令 + +| 子命令 | 参数 | 说明 | MVP | +|--------|------|------|:---:| +| setup | — | 引导式同步配置（检测 git remote → 生成 sync-mapping.md） | ✅ | +| link | CR-ID #外部ID | 关联 CR 与外部实体 | ✅ | +| push | [CR-ID] [--dry-run] | 推送 devpace 状态到外部（指定 CR 或全部已关联） | ✅ | +| unlink | CR-ID | 解除 CR 与外部实体的关联 | ✅ | +| create | CR-ID | 从 CR 元数据创建外部 Issue 并自动关联 | ✅ | +| pull | [CR-ID] | 拉取外部状态到 devpace | Phase 19 | +| sync | [CR-ID] | 双向同步 | Phase 20 | +| resolve | CR-ID | 解决同步冲突 | Phase 20 | +| status | — | 查看所有 CR 的同步状态和外部链接 | ✅ | + +无参数时默认 `status`。 + +## 流程 + +1. 读取 `.devpace/integrations/sync-mapping.md` + - 不存在 → 引导运行 `setup` +2. 根据子命令路由到对应操作（详见 `sync-procedures.md`） +3. 执行后更新 sync-mapping.md 关联记录 + +### 执行路由 + +| 参数 | 执行规程 | +|------|---------| +| `setup` | sync-procedures.md §2 | +| `link` | sync-procedures.md §3 | +| `push` | sync-procedures.md §4 | +| `unlink` | sync-procedures.md §6 | +| `create` | sync-procedures.md §7 | +| `pull` | Phase 19，暂不支持 | +| `sync` | Phase 20，暂不支持 | +| `resolve` | Phase 20，暂不支持 | +| `status` | sync-procedures.md §5 | +| （空） | 等同 `status` | + +## 输出 + +- **setup**：配置摘要（平台 + 仓库 + 同步模式） +- **link**：关联确认（CR ↔ 外部实体） +- **push**：同步结果表（CR | 状态 | 外部操作 | 结果） +- **status**：同步状态表（CR | 外部链接 | 最后同步 | 状态一致性） +- **unlink**：解除关联确认（CR ↔ 外部实体已解除） +- **create**：创建并关联确认（CR → 外部 Issue #{编号} 已创建并关联） diff --git a/skills/pace-sync/sync-adapter-github.md b/skills/pace-sync/sync-adapter-github.md new file mode 100644 index 0000000..6577d78 --- /dev/null +++ b/skills/pace-sync/sync-adapter-github.md @@ -0,0 +1,74 @@ +# GitHub 适配器（gh CLI） + +> **职责**：定义 /pace-sync 在 GitHub 平台上的具体执行方式。sync-procedures.md 定义"做什么"，本文件定义"在 GitHub 上怎么做"。 + +## 前置条件 + +- `gh` CLI 已安装且已认证（`gh auth status`） +- 不可用时降级（sync-procedures.md §8 降级行为生效） + +## 操作表 + +sync-procedures.md 子命令使用"操作语义"描述步骤，Claude 在本表中查找对应 gh CLI 命令执行。 + +| 操作语义 | gh CLI 命令 | 说明 | +|---------|------------|------| +| 验证连接 | `gh repo view {owner}/{repo} --json name` | 检查仓库可访问 | +| 创建工作项 | `gh issue create --title "{title}" --body "{body}" --label "{labels}"` | 创建 Issue | +| 获取状态 | `gh issue view {number} --json state,labels,title,locked` | 查询 Issue 状态 | +| 更新状态标记 | `gh issue edit {number} --remove-label "{old}" --add-label "{new}"` | 标签增删 | +| 添加评论 | `gh issue comment {number} --body "{comment}"` | 写入 Comment | +| 关闭工作项 | `gh issue edit {number} --state closed` | 关闭 Issue | +| 列出工作项 | `gh issue list --json number,title,state,labels --limit 50` | 查询候选 | +| 创建标签 | `gh label create "{name}" --description "devpace sync" --color "ededed"` | 预创建标签 | + +## 状态更新策略 + +GitHub 使用 Issue state（open/closed）+ 标签组合表示状态。 + +| devpace 状态 | GitHub 操作 | +|-------------|-----------| +| created | 确保 Issue open + 添加 `backlog` 标签 | +| developing | 移除 `backlog` + 添加 `in-progress` 标签 | +| verifying | 移除 `in-progress` + 添加 `needs-review` 标签 | +| in_review | 移除 `needs-review` + 添加 `awaiting-approval` 标签 | +| approved | 移除 `awaiting-approval` + 添加 `approved` 标签 | +| merged | 关闭 Issue + 添加 `done` 标签 | +| released | 添加 `released` 标签 | +| paused | 添加 `on-hold` 标签 | + +## setup 补充步骤 + +### 标签预创建 + +setup 完成基础配置后，预创建所有映射标签： + +```bash +for label in backlog in-progress needs-review awaiting-approval approved done released on-hold gate-1-passed gate-2-passed gate-3-passed; do + gh label create "$label" --description "devpace sync" --color "ededed" 2>/dev/null || true +done +``` + +gh 不可用时跳过，在配置摘要中标注"标签未预创建"。 + +## Issue 状态预检查（push 前） + +push 前检查目标 Issue 是否可更新： +- state=closed 且 devpace 状态非 merged/released → 警告跳过 +- locked=true → 警告跳过 + +## Gate 结果标签 + +| Gate | 结果 | 标签操作 | +|------|------|---------| +| Gate 1 | 通过 | 添加 `gate-1-passed` 标签 | +| Gate 2 | 通过 | 添加 `gate-2-passed` 标签 | +| Gate 3 | 通过 | 添加 `gate-3-passed` 标签 | + +未通过时仅添加 Comment，不添加标签。 + +> **Phase 19 扩展**：Schema 定义的 Gate 2 PR Review（approve）和 Gate 3 PR Review（request changes）操作在 Phase 19 实现。当前 MVP 统一使用 Comment + 标签。 + +## 限流保护 + +每次 API 调用后等待 1 秒。检测到 403/429 → 暂停 60 秒重试 1 次。重试仍失败 → 标记跳过。 diff --git a/skills/pace-sync/sync-procedures.md b/skills/pace-sync/sync-procedures.md new file mode 100644 index 0000000..68644f2 --- /dev/null +++ b/skills/pace-sync/sync-procedures.md @@ -0,0 +1,249 @@ +# pace-sync 同步操作规程 + +> **职责**：定义 /pace-sync 各子命令的详细执行步骤。SKILL.md 定义"做什么"，本文件定义"怎么做"。 + +## §0 速查 + +| 子命令 | 前置条件 | 输出 | +|--------|---------|------| +| setup | 平台工具可用 + git remote 已配置 | sync-mapping.md | +| link | sync-mapping.md 存在 + CR 存在 + 外部实体存在 | CR 外部关联 + 关联记录 | +| push | CR 已关联 | 外部状态更新 | +| unlink | CR 存在 + 有外部关联 | 关联解除确认 | +| create | CR 存在 + sync-mapping.md 存在 + 平台工具可用 | 创建工作项 + 自动关联 | +| status | sync-mapping.md 存在 | 同步状态表 | + +> Phase 19/20 子命令（pull/sync/resolve）暂未实现，用户输入时提示"此功能计划在 Phase 19/20 支持"。 + +## §1 适配器路由 + +> Claude 根据 sync-mapping.md "平台"字段加载对应适配器文件执行。 + +| 平台 | 适配器文件 | 工具 | 状态 | +|------|-----------|------|------| +| GitHub | sync-adapter-github.md | gh CLI | 可用 | +| Linear | sync-adapter-linear.md | MCP | Phase 19 | +| Jira | sync-adapter-jira.md | MCP/CLI | Phase 19+ | + +**执行规则**：子命令步骤使用操作语义（如"验证连接"、"更新状态标记"），Claude 在适配器文件的操作表中查找对应命令执行。 + +## §2 setup — 引导式配置 + +**前置检查**： +1. 检查平台工具是否可用（不可用 → 提示安装，不阻断） +2. 检查 `.devpace/` 是否存在（不存在 → 引导 /pace-init） +3. 检查 `sync-mapping.md` 是否已存在（已存在 → 提示"同步已配置，是否重新配置？"，确认后继续，否则退出） + +**执行步骤**： +1. 读取 git remote：`git remote get-url origin` → 提取 owner/repo +2. 向用户确认： + - 仓库：{owner}/{repo} + - 同步模式：push（推荐 MVP）/ bidirectional + - 冲突策略：ask-user（推荐 MVP） +3. 执行适配器"验证连接"操作 +4. 生成 `.devpace/integrations/sync-mapping.md`（按 Plugin `knowledge/_schema/sync-mapping-format.md` Schema） +5. 执行适配器 setup 补充步骤（如预创建状态标记等平台初始化操作） + - 平台工具不可用时跳过，在配置摘要中标注 +6. 更新 `.devpace/integrations/config.md` 的"外部同步"section（如 config.md 存在） +7. 输出配置摘要 + +**配置摘要格式**： +``` +同步配置完成： +- 平台：{平台类型} ({连接标识}) +- 同步模式：push +- 连接状态：✅ 已验证 / ⚠️ 未验证（平台工具不可用） +- 初始化状态：✅ 已完成 / ⚠️ 未完成（平台工具不可用） +下一步：用 /pace-sync link CR-xxx #外部编号 关联变更请求 +``` + +**降级**：平台工具不可用时仍生成配置文件，标注"连接未验证"。 + +## §3 link — 关联 CR 与外部实体 + +**输入解析**：`$1` = CR-ID（如 CR-003 或 003），`$2` = 外部 ID（如 #42 或 42） + +**执行步骤**： +1. 验证 CR 存在：检查 `.devpace/backlog/CR-{id}.md` +2. 验证外部实体存在：执行适配器"获取状态"操作（参数：外部实体编号） +3. 写入 CR 文件"外部关联"字段（格式按平台，如 GitHub：`[github:#N](https://github.com/owner/repo/issues/N)`） +4. 更新 sync-mapping.md 关联记录表（追加行） +5. 输出确认：CR-{id} ↔ 外部实体 #{编号} 已关联 + +**关联记录行格式**（按 Plugin `knowledge/_schema/sync-mapping-format.md`）： +```markdown +| CR-{id} | {平台}#{编号} | {YYYY-MM-DD HH:mm} | — | +``` + +**错误处理**： +- CR 不存在 → 提示用户 +- 外部实体不存在 → 提示用户确认 ID +- CR 已有关联 → 提示已关联，确认是否覆盖 + +## §4 push — 推送状态到外部 + +**输入**：`$1` = CR-ID（可选，省略则推送所有已关联 CR） + +**模式检测**：`$ARGUMENTS` 包含 `--dry-run` 时进入预览模式。 + +**执行步骤**： +1. 读取 sync-mapping.md 关联记录 + - 关联记录为空 → 输出"当前没有已关联的外部实体。用 /pace-sync link CR-xxx #Issue编号 创建关联。"并退出 +2. 对每个目标 CR： + a. 读取 CR 当前状态 + b. 查询状态映射表 → 获取对应外部状态 + c. 执行适配器"获取状态"操作 → 查询外部当前状态 + d. **外部实体状态预检查**：按适配器"状态预检查"规则验证外部实体可更新。不可更新 → 输出警告并跳过 + e. 比较：一致 → 跳过，不一致 → 执行更新 + f. **dry-run 模式**：输出将要执行的操作后停止，不实际执行。预览格式：`[预览] 将对 CR-{id} (#{编号}) 执行：{操作描述}`。所有 CR 处理完后输出汇总表（同正常模式格式，结果列显示"预览"） + g. 执行适配器"状态更新策略"中对应的操作 + h. 生成语义 Comment 并执行适配器"添加评论"操作 + i. 更新 sync-mapping.md 最后同步时间 + j. **限流保护**：按适配器限流规则执行（含等待、重试、跳过逻辑） +3. 输出同步结果表 + +**语义 Comment 生成规则**（替代固定模板）： + +Claude 读取 CR 上下文后生成语义丰富的 Comment，而不是套用固定模板。 + +**信息采集**： +1. CR 标题和意图描述 +2. 当前状态和转换原因 +3. 最近的 Gate 结果（如有） +4. 关键验收条件达成情况（如有） + +**Comment 格式**： +``` +🔄 [{状态}] {CR 标题} + +{1-2 句上下文说明，如"用户认证模块进入审查，Gate 1 已通过 12/12 检查项"} + +{仅在 merged 时附加：关键交付摘要} +``` + +**约束**： +- 不超过 5 行 +- 不包含 devpace 内部术语（如 checkpoint、state.md） +- 信息采集失败时回退到简单格式：`🔄 [{状态}] {CR 标题}` + +**同步结果表格式**： +``` +| CR | 状态 | 外部操作 | 结果 | +|----|------|---------|------| +| CR-003 | developing | 更新状态标记 | ✅ | +| CR-005 | merged | 关闭工作项 | ✅ | +``` + +### §4.8 Gate 结果同步 + +Gate 检查完成时，如果 CR 有外部关联，自动推送结果到外部。 + +**触发时机**：Gate 1 完成后 | Gate 2 完成后 | Gate 3 待处理时 + +**同步动作**（按 sync-mapping-format.md "Gate 结果同步" section）： + +| Gate | 结果 | 外部操作 | +|------|------|---------| +| Gate 1 | 通过 | 适配器"添加评论"（检查通过摘要）+ 适配器 Gate 标签操作 | +| Gate 1 | 未通过 | 适配器"添加评论"（失败项摘要） | +| Gate 2 | 通过 | 适配器"添加评论"（审查通过）+ 适配器 Gate 标签操作 | +| Gate 2 | 未通过 | 适配器"添加评论"（未通过项列表） | +| Gate 3 | 待处理 | 适配器"添加评论"（审批摘要）+ 请求 review | +| Gate 3 | 通过 | 适配器"添加评论"（已批准）+ 适配器 Gate 标签操作 | + +**Comment 格式**（遵循语义 Comment 规则）： +``` +✅ Gate {N} 通过：{1 句摘要} +``` +或 +``` +❌ Gate {N} 未通过：{失败项数}/{总数}，主要问题：{问题摘要} +``` + +**约束**： +- sync-mapping.md 不存在 → 静默跳过 +- CR 无外部关联 → 静默跳过 +- 平台工具不可用 → 在 Gate 结果输出中附加提醒"外部同步失败" + +## §5 status — 同步状态查看 + +**执行步骤**： +1. 读取 sync-mapping.md +2. 对每个关联记录： + a. 读取 CR 当前状态 + b. 执行适配器"获取状态"操作（可选——平台工具不可用时显示"未知"） + c. 比较一致性 +3. 输出同步状态表 + +**输出格式**： +``` +| CR | 外部链接 | devpace 状态 | 外部状态 | 一致性 | 最后同步 | +|----|---------|-------------|---------|--------|---------| +| CR-003 | #42 | developing | in-progress | ✅ | 02-25 10:30 | +| CR-005 | #18 | merged | open | ❌ 需推送 | 02-24 15:00 | +``` + +**无关联记录时**： +``` +当前没有已关联的外部实体。 +用 /pace-sync link CR-xxx #Issue编号 创建关联。 +``` + +## §6 unlink — 解除关联 + +**输入**：`$1` = CR-ID + +**执行步骤**： +1. 验证 CR 存在且有外部关联 +2. 清除 CR 文件中的"外部关联"字段 +3. 从 sync-mapping.md 关联记录表中移除对应行 +4. 输出确认：CR-{id} 已解除与 {外部实体} 的关联 + +**错误处理**： +- CR 无外部关联 → 提示"CR-{id} 当前没有外部关联" +- CR 不存在 → 提示用户 + +## §7 create — 从 CR 创建外部工作项 + +**输入**：`$1` = CR-ID + +**执行步骤**： +1. 验证 CR 存在且无外部关联 +2. 读取 CR 元数据：标题、意图描述、验收条件、关联 PF +3. 生成工作项描述： + ``` + ## 变更请求：{CR 标题} + + **意图**：{意图描述} + + **验收条件**： + {逐条列出验收条件} + + **关联功能**：{PF 名称} + + --- + _由 devpace 自动创建_ + ``` +4. 查询状态映射表获取当前状态对应的外部状态标记 +5. 执行适配器"创建工作项"操作（参数：标题、描述、状态标记） +6. 自动执行 link（复用 §3 流程） +7. 输出确认：CR-{id} → 外部工作项 #{编号} 已创建并关联 + +**错误处理**： +- CR 已有外部关联 → 提示已关联，确认是否创建新工作项并覆盖 +- 平台工具不可用 → 提示安装 +- CR 不存在 → 提示用户 + +## §8 降级行为 + +降级矩阵定义于 `knowledge/_schema/sync-mapping-format.md` "降级行为" section（权威源）。各子命令步骤中已内嵌具体降级逻辑。 + +## §9 与现有 Skill 的集成 + +| Skill | 集成方式 | +|-------|---------| +| pace-dev | CR 状态转换后 sync-push Hook 提醒推送 | +| pace-change | 变更操作后同步状态到外部 | +| pace-release | Release 状态变化同步（Phase 19） | +| pace-review | Gate 2 结果同步为 PR Review（Phase 19） | +| pace-status | 展示同步状态和外部链接 | diff --git a/tests/conftest.py b/tests/conftest.py index 36a5b90..287c077 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -24,6 +24,7 @@ "pace-release", "pace-retro", "pace-review", + "pace-sync", "pace-role", "pace-status", "pace-test", @@ -31,7 +32,7 @@ "pace-trace", ] -SCHEMA_FILES = ["checks-format.md", "context-format.md", "cr-format.md", "insights-format.md", "integrations-format.md", "iteration-format.md", "project-format.md", "release-format.md", "risk-format.md", "state-format.md", "test-baseline-format.md", "test-strategy-format.md"] +SCHEMA_FILES = ["checks-format.md", "context-format.md", "cr-format.md", "insights-format.md", "integrations-format.md", "iteration-format.md", "project-format.md", "release-format.md", "risk-format.md", "state-format.md", "sync-mapping-format.md", "test-baseline-format.md", "test-strategy-format.md"] TEMPLATE_FILES = [ "state.md", diff --git a/tests/static/test_hooks.py b/tests/static/test_hooks.py index 48cebfa..a5bf5c0 100644 --- a/tests/static/test_hooks.py +++ b/tests/static/test_hooks.py @@ -26,7 +26,7 @@ } EXPECTED_SCRIPTS_SH = ["session-start.sh", "session-stop.sh", "pre-compact.sh"] -EXPECTED_SCRIPTS_MJS = ["pre-tool-use.mjs", "post-cr-update.mjs", "intent-detect.mjs", "subagent-stop.mjs", "pulse-counter.mjs", "post-tool-failure.mjs"] +EXPECTED_SCRIPTS_MJS = ["pre-tool-use.mjs", "post-cr-update.mjs", "intent-detect.mjs", "subagent-stop.mjs", "pulse-counter.mjs", "post-tool-failure.mjs", "sync-push.mjs"] EXPECTED_SCRIPTS = EXPECTED_SCRIPTS_SH + EXPECTED_SCRIPTS_MJS @@ -221,3 +221,16 @@ def test_tc_hk_15_plugin_settings_exist(self): assert settings_path.exists(), "settings.json not found at Plugin root" data = json.loads(settings_path.read_text(encoding="utf-8")) assert "agents" in data, "settings.json should have agents section" + + def test_tc_hk_16_sync_push_async_configured(self): + """TC-HK-16: sync-push.mjs is configured as async in PostToolUse hooks.""" + data = json.loads(HOOKS_JSON.read_text(encoding="utf-8")) + found = False + for config in data["hooks"].get("PostToolUse", []): + for hook in config.get("hooks", []): + if "sync-push" in hook.get("command", ""): + found = True + assert hook.get("async") is True, ( + "sync-push.mjs should have async:true for non-blocking execution" + ) + assert found, "sync-push.mjs not found in PostToolUse hooks" diff --git a/tests/static/test_sync_maintenance.py b/tests/static/test_sync_maintenance.py index 096467c..c826659 100644 --- a/tests/static/test_sync_maintenance.py +++ b/tests/static/test_sync_maintenance.py @@ -4,6 +4,7 @@ - Command table in devpace-rules.md vs actual skill directories - accept capability keywords in pace-test/SKILL.md vs devpace-rules.md - Schema mapping table in devpace-rules.md vs _schema/ directory +- Feature docs sub-command list vs SKILL.md """ import re @@ -14,6 +15,8 @@ RULES_FILE = DEVPACE_ROOT / "rules" / "devpace-rules.md" PACE_TEST_SKILL = DEVPACE_ROOT / "skills" / "pace-test" / "SKILL.md" SCHEMA_DIR = DEVPACE_ROOT / "knowledge" / "_schema" +FEATURES_DIR = DEVPACE_ROOT / "docs" / "features" +SKILLS_DIR = DEVPACE_ROOT / "skills" def _read_text(path): @@ -148,3 +151,101 @@ def test_tc_sm_03_schema_files_exist(self): assert not missing, ( f"Expected schema files missing from _schema/: {sorted(missing)}" ) + + def test_tc_sm_04_feature_docs_subcommand_sync(self): + """TC-SM-04: feature docs sub-command list matches SKILL.md. + + For each skill that has a docs/features/.md, verify that + the sub-commands listed in the feature doc match those in SKILL.md. + """ + if not FEATURES_DIR.is_dir(): + pytest.skip("docs/features/ directory does not exist yet") + + # Find all EN feature docs (exclude _zh translations) + feature_docs = [ + f for f in FEATURES_DIR.iterdir() + if f.suffix == ".md" + and f.stem.startswith("pace-") + and not f.stem.endswith("_zh") + ] + + if not feature_docs: + pytest.skip("No feature docs found in docs/features/") + + errors = [] + for doc_path in feature_docs: + skill_name = doc_path.stem # e.g., "pace-sync" + skill_md = SKILLS_DIR / skill_name / "SKILL.md" + + if not skill_md.exists(): + errors.append( + f"Feature doc {doc_path.name} has no matching " + f"skills/{skill_name}/SKILL.md" + ) + continue + + # Extract sub-commands from SKILL.md (table rows in ### 子命令) + skill_text = skill_md.read_text(encoding="utf-8") + subcmd_section = re.search( + r"### 子命令\s*\n(.*?)(?=\n### |\n## |\Z)", + skill_text, + re.DOTALL, + ) + if not subcmd_section: + continue # No sub-command table, skip + + # Extract sub-command names from table rows: | name | ... + skill_subcmds = set( + re.findall(r"^\|\s*(\w+)\s*\|", subcmd_section.group(1), re.MULTILINE) + ) + # Remove table header words + skill_subcmds -= {"子命令", "---"} + + # Extract sub-commands from feature doc (### `name` headings + # under ## Command Reference) + doc_text = doc_path.read_text(encoding="utf-8") + cmd_ref_section = re.search( + r"## Command Reference\s*\n(.*?)(?=\n## [^#]|\Z)", + doc_text, + re.DOTALL, + ) + if not cmd_ref_section: + # Try Chinese heading + cmd_ref_section = re.search( + r"## 命令参考\s*\n(.*?)(?=\n## [^#]|\Z)", + doc_text, + re.DOTALL, + ) + if not cmd_ref_section: + continue + + doc_subcmds = set( + re.findall(r"### `(\w+)`", cmd_ref_section.group(1)) + ) + + # Filter to only MVP sub-commands (marked ✅ in SKILL.md) + mvp_lines = re.findall( + r"^\|\s*(\w+)\s*\|.*?\|\s*✅\s*\|", + subcmd_section.group(1), + re.MULTILINE, + ) + skill_mvp_subcmds = set(mvp_lines) if mvp_lines else skill_subcmds + + missing_in_doc = skill_mvp_subcmds - doc_subcmds + extra_in_doc = doc_subcmds - skill_subcmds + + if missing_in_doc: + errors.append( + f"{doc_path.name}: MVP sub-commands in SKILL.md but " + f"missing from feature doc: {sorted(missing_in_doc)}" + ) + if extra_in_doc: + errors.append( + f"{doc_path.name}: sub-commands in feature doc but " + f"not in SKILL.md: {sorted(extra_in_doc)}" + ) + + assert not errors, ( + "Feature doc ↔ SKILL.md sub-command drift detected:\n" + + "\n".join(f" - {e}" for e in errors) + ) diff --git a/tests/static/test_template_placeholders.py b/tests/static/test_template_placeholders.py index a8e8d4e..8d2dbfe 100644 --- a/tests/static/test_template_placeholders.py +++ b/tests/static/test_template_placeholders.py @@ -82,7 +82,7 @@ def test_tc_tp_04_no_placeholders_in_non_template_product(self): continue for f in dirpath.rglob("*.md"): # Skip template directory, SKILL.md, and procedure files (which document placeholder syntax) - if "templates" in f.parts or f.name == "SKILL.md" or f.name.endswith("-procedures.md"): + if "templates" in f.parts or f.name == "SKILL.md" or "procedures" in f.name: continue content = f.read_text(encoding="utf-8") matches = PLACEHOLDER_RE.findall(content)