dev-playbooks-cn 1.0.0

package/templates/dev-playbooks/README.md

@@ -0,0 +1,458 @@
+# DevBooks
+
+**An agentic AI development workflow for Claude Code / Codex CLI**
+
+> Turn large changes into a controlled, traceable, verifiable loop: Skills + quality gates + role isolation.
+
+[![npm](https://img.shields.io/npm/v/dev-playbooks-cn)](https://www.npmjs.com/package/dev-playbooks-cn)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](../LICENSE)
+
+---
+
+## Why DevBooks?
+
+AI coding assistants are powerful, but often **unpredictable**:
+
+| Pain point | Outcome |
+|------|------|
+| **AI self-declares "done"** | Tests fail, edge cases are missed |
+| **Writing tests and code in the same chat** | Tests turn into “pass tests” instead of spec verification |
+| **No verification gates** | False completion silently ships |
+| **Only works for greenfield (0→1)** | Brownfield repos have no on-ramp |
+| **Too few commands** | Complex changes are not just "spec/apply/archive" |
+
+**DevBooks provides**:
+- **Evidence-based done**: completion is defined by tests/build/evidence, not AI self-evaluation
+- **Enforced role isolation**: Test Owner and Coder must work in separate conversations
+- **Multiple quality gates**: green evidence checks, task completion, role boundary checks
+- **21 Skills**: proposal, design, debate, review, entropy metrics, federation, and more
+
+---
+
+## DevBooks At a Glance (Comparison)
+
+| Dimension | DevBooks | OpenSpec | spec-kit | No spec |
+|------|----------|----------|----------|--------|
+| Spec-driven workflow | Yes | Yes | Yes | No |
+| Artifact traceability | Change package (proposal/design/spec/tasks/verification/evidence) | Mostly folder/file organization | Docs + tasks orchestration | None |
+| Role & responsibility boundaries | **Enforced** (Test Owner / Coder) | Convention-based (not enforced) | Convention-based (not enforced) | None |
+| Definition of Done (DoD) | **Evidence + gates** (tests/build/audit) | Manual definition/checks | Manual definition/checks | Often subjective |
+| Code quality assurance | Gates + metrics (entropy/hotspots) + review roles | External tools / manual review | External tools / manual review | Unstable |
+| Impact analysis | CKB graph capability (falls back to grep) | Text search / manual reasoning | Text search / manual reasoning | Easy to miss |
+| Brownfield onboarding | Baseline specs/glossary/minimal verification anchors | Manual | Limited | - |
+| Automation coverage | 21 Skills (proposal→implementation→archive loop) | 3 core commands | Toolkit (greenfield-leaning) | - |
+
+---
+
+## How It Works
+
+```
+                           DevBooks Workflow
+
+    PROPOSAL stage                 APPLY stage                      ARCHIVE stage
+    (no coding)                    (role isolation enforced)         (quality gates)
+
+    ┌─────────────────┐            ┌─────────────────┐              ┌─────────────────┐
+    │  /devbooks:     │            │   Chat A        │              │  /devbooks:     │
+    │   proposal      │            │  ┌───────────┐  │              │   gardener      │
+    │   impact        │────────────│  │Test Owner │  │──────────────│   delivery      │
+    │   design        │            │  │(Red first)│  │              │                 │
+    │   spec          │            │  └───────────┘  │              │  Gates:         │
+    │   plan          │            │                 │              │  ✓ Green evidence│
+    └─────────────────┘            │   Chat B        │              │  ✓ Tasks done   │
+           │                       │  ┌───────────┐  │              │  ✓ Role boundary│
+           ▼                       │  │  Coder    │  │              │  ✓ No failures  │
+    ┌─────────────────┐            │  │(no tests!)│  │              └─────────────────┘
+    │ Triangle debate │            │  └───────────┘  │
+    │ Author/Challenger│            └─────────────────┘
+    │ /Judge          │
+    └─────────────────┘
+```
+
+**Hard constraint**: Test Owner and Coder **must work in separate conversations**. This is not a suggestion. Coder cannot modify `tests/**`. “Done” is defined by tests/build verification, not AI self-evaluation.
+
+---
+
+## Quick Start
+
+### Supported AI tools
+
+| Tool | Slash commands | Natural language |
+|------|-----------|----------|
+| **Claude Code** | `/devbooks:*` | Yes |
+| **Codex CLI** | `/devbooks:*` | Yes |
+| Other assistants | - | “Run DevBooks proposal skill…” |
+
+### Install & init
+
+**Install via npm (recommended):**
+
+```bash
+# global install
+npm install -g dev-playbooks-cn
+
+# init inside your project
+dev-playbooks-cn init
+```
+
+**One-off usage:**
+
+```bash
+npx dev-playbooks-cn@latest init
+```
+
+**From source (contributors):**
+
+```bash
+../scripts/install-skills.sh
+```
+
+### Install targets
+
+After initialization:
+- Claude Code: `~/.claude/skills/devbooks-*`
+- Codex CLI: `$CODEX_HOME/skills/devbooks-*` (default `~/.codex/skills/devbooks-*`)
+
+### Quick integration
+
+DevBooks uses two directory roots:
+
+| Directory | Purpose | Default |
+|------|------|--------|
+| `<truth-root>` | Current specs (read-only truth) | `dev-playbooks/specs/` |
+| `<change-root>` | Change packages (workspace) | `dev-playbooks/changes/` |
+
+See `../docs/DevBooks集成模板（协议无关）.md` (currently in Chinese), or use `../docs/DevBooks安装提示词.md` to let your assistant configure it automatically.
+
+---
+
+## Day-to-Day Change Workflow
+
+### Use Router (recommended)
+
+```
+/devbooks:router <your request>
+```
+
+Router analyzes your request and outputs an execution plan (which command to run next).
+
+### Direct commands
+
+Once you know the flow, call the Skills directly:
+
+**1) Proposal stage (no coding)**
+
+```
+/devbooks:proposal Add OAuth2 user authentication
+```
+
+Artifacts: `proposal.md` (required), `design.md`, `tasks.md`
+
+**2) Apply stage (role isolation enforced)**
+
+You must use **two separate conversations**:
+
+```
+# Chat A - Test Owner
+/devbooks:test add-oauth2
+
+# Chat B - Coder
+/devbooks:code add-oauth2
+```
+
+- Test Owner: writes `verification.md` + tests, runs **Red** first
+- Coder: implements per `tasks.md`, makes gates **Green** (cannot modify tests)
+
+**3) Review stage**
+
+```
+/devbooks:review add-oauth2
+```
+
+**4) Archive stage**
+
+```
+/devbooks:gardener add-oauth2
+```
+
+---
+
+## Command Reference
+
+### Proposal stage
+
+| Command | Skill | Description |
+|------|-------|------|
+| `/devbooks:router` | devbooks-router | Route to the right Skill |
+| `/devbooks:proposal` | devbooks-proposal-author | Create a change proposal |
+| `/devbooks:impact` | devbooks-impact-analysis | Cross-module impact analysis |
+| `/devbooks:challenger` | devbooks-proposal-challenger | Challenge a proposal |
+| `/devbooks:judge` | devbooks-proposal-judge | Adjudicate a proposal |
+| `/devbooks:debate` | devbooks-proposal-debate-workflow | Triangle debate (Author/Challenger/Judge) |
+| `/devbooks:design` | devbooks-design-doc | Create a design doc |
+| `/devbooks:spec` | devbooks-spec-contract | Define specs & contracts |
+| `/devbooks:c4` | devbooks-c4-map | Generate a C4 map |
+| `/devbooks:plan` | devbooks-implementation-plan | Create an implementation plan |
+
+### Apply stage
+
+| Command | Skill | Description |
+|------|-------|------|
+| `/devbooks:test` | devbooks-test-owner | Test Owner role (separate chat required) |
+| `/devbooks:code` | devbooks-coder | Coder role (separate chat required) |
+| `/devbooks:backport` | devbooks-design-backport | Backport discoveries to design |
+
+### Review stage
+
+| Command | Skill | Description |
+|------|-------|------|
+| `/devbooks:review` | devbooks-code-review | Code review (readability/consistency) |
+| `/devbooks:test-review` | devbooks-test-reviewer | Test quality & coverage review |
+
+### Archive stage
+
+| Command | Skill | Description |
+|------|-------|------|
+| `/devbooks:gardener` | devbooks-spec-gardener | Maintain/dedupe specs |
+| `/devbooks:delivery` | devbooks-delivery-workflow | End-to-end delivery workflow |
+
+### Standalone Skills
+
+| Command | Skill | Description |
+|------|-------|------|
+| `/devbooks:entropy` | devbooks-entropy-monitor | System entropy metrics |
+| `/devbooks:federation` | devbooks-federation | Cross-repo federation analysis |
+| `/devbooks:bootstrap` | devbooks-brownfield-bootstrap | Brownfield project bootstrap |
+| `/devbooks:index` | devbooks-index-bootstrap | Generate a SCIP index |
+
+---
+
+## DevBooks Comparisons
+
+### vs. OpenSpec
+
+[OpenSpec](https://github.com/Fission-AI/OpenSpec) is a lightweight spec-driven framework with three core commands (proposal/apply/archive), organizing changes by feature folders.
+
+**What DevBooks adds:**
+- **Role isolation**: hard boundary between Test Owner and Coder (separate chats)
+- **Quality gates**: 5+ verification gates to block false completion
+- **21 Skills**: proposal, debate, review, entropy metrics, federation, etc.
+- **Evidence-based done**: tests/build define “done”, not self-evaluation
+
+**Choose OpenSpec**: you want a lightweight spec workflow.
+
+**Choose DevBooks**: you need role separation and verification gates for larger changes.
+
+### vs. spec-kit
+
+[GitHub spec-kit](https://github.com/github/spec-kit) is a spec-driven toolkit with a constitution file, multi-step refinement, and structured planning.
+
+**What DevBooks adds:**
+- **Brownfield-first**: generates baseline specs for existing repos
+- **Role isolation**: test authoring and implementation are separated
+- **Quality gates**: runtime verification, not just workflow guidance
+- **Prototype mode**: safe experiments without polluting main `src/`
+
+**Choose spec-kit**: greenfield projects with supported AI tools.
+
+**Choose DevBooks**: brownfield repos or when you want enforced gates.
+
+### vs. Kiro.dev
+
+[Kiro](https://kiro.dev/) is an AWS agentic IDE with a three-phase workflow (EARS requirements, design, tasks), but stores specs separately from implementation artifacts.
+
+**DevBooks differences:**
+- **Change package**: proposal/design/spec/plan/verification/evidence in one place for lifecycle traceability
+- **Role isolation**: Test Owner and Coder are separated
+- **Quality gates**: verified through gates, not just task completion
+
+**Choose Kiro**: you want an IDE experience and AWS ecosystem integration.
+
+**Choose DevBooks**: you want change packages to bundle artifacts and enforce role boundaries.
+
+### vs. no spec
+
+Without specs, the assistant generates code from vague prompts, leading to unpredictable output, scope creep, and “hallucinated completion”.
+
+**DevBooks brings:**
+- Specs agreed before implementation
+- Quality gates that verify real completion
+- Role isolation to prevent self-verification
+- Evidence chain per change
+
+---
+
+## Core Principles
+
+| Principle | Meaning |
+|------|------|
+| **Protocol first** | truth/change/archive live in the repo, not only in chat logs |
+| **Anchor first** | done is defined by tests/static checks/build/evidence |
+| **Role isolation** | Test Owner and Coder must work in separate conversations |
+| **Truth root separation** | `<truth-root>` is read-only truth; `<change-root>` is the workspace |
+| **Structural gates** | prioritize complexity/coupling/test quality, not proxy metrics |
+
+---
+
+## Advanced Features
+
+<details>
+<summary><strong>Quality gates</strong></summary>
+
+DevBooks uses quality gates to block “false done”:
+
+| Gate | Trigger mode | What it checks |
+|------|----------|----------|
+| Green evidence | archive, strict | `evidence/green-final/` exists and is non-empty |
+| Task completion | strict | all tasks are done or SKIP-APPROVED |
+| Test failure block | archive, strict | no failures in green evidence |
+| P0 skip approval | strict | P0 skips require an approval record |
+| Role boundary | apply --role | Coder cannot modify tests/, Test Owner cannot modify src/ |
+
+Core scripts (in `../skills/devbooks-delivery-workflow/scripts/`):
+- `change-check.sh --mode proposal|apply|archive|strict`
+- `handoff-check.sh` - handoff boundary checks
+- `audit-scope.sh` - full audit scan
+- `progress-dashboard.sh` - progress visualization
+
+</details>
+
+<details>
+<summary><strong>Prototype mode</strong></summary>
+
+When the technical approach is uncertain:
+
+1. Create a prototype: `change-scaffold.sh <change-id> --prototype`
+2. Test Owner with `--prototype`: characterization tests (no Red baseline required)
+3. Coder with `--prototype`: output to `prototype/src/` (isolates main src)
+4. Promote or discard: `prototype-promote.sh <change-id>`
+
+Prototype mode prevents experimental code from polluting the main tree.
+
+Scripts live in `../skills/devbooks-delivery-workflow/scripts/`.
+
+</details>
+
+<details>
+<summary><strong>Entropy monitoring</strong></summary>
+
+DevBooks tracks four dimensions of system entropy:
+
+| Metric | What it measures |
+|------|----------|
+| Structural entropy | module complexity and coupling |
+| Change entropy | change patterns and volatility |
+| Test entropy | coverage/quality decay over time |
+| Dependency entropy | external dependency health |
+
+Use `/devbooks:entropy` to generate reports and identify refactor opportunities.
+
+Scripts (in `../skills/devbooks-entropy-monitor/scripts/`): `entropy-measure.sh`, `entropy-report.sh`
+
+</details>
+
+<details>
+<summary><strong>Brownfield project bootstrap</strong></summary>
+
+When `<truth-root>` is empty:
+
+```
+/devbooks:bootstrap
+```
+
+Generates:
+- project profile and glossary
+- baseline specs from existing code
+- minimal verification anchors
+- module dependency map
+- technical debt hotspots
+
+</details>
+
+<details>
+<summary><strong>Cross-repo federation</strong></summary>
+
+For multi-repo analysis:
+
+```
+/devbooks:federation
+```
+
+Analyzes cross-repo contracts and dependencies to support coordinated changes.
+
+</details>
+
+<details>
+<summary><strong>MCP auto-detection</strong></summary>
+
+DevBooks Skills support graceful MCP (Model Context Protocol) degradation: you can run the full workflow without MCP/CKB; when CKB (Code Knowledge Base) is detected, DevBooks automatically enables graph-based capabilities for more accurate “scope/reference/call chain” analysis.
+
+### What is it for?
+
+- **More accurate impact analysis**: upgrades from “file-level guesses” to “symbol references + call graphs”
+- **More focused reviews**: automatically pulls hotspots and prioritizes high-risk areas (tech debt/high churn)
+- **Less manual grep**: reduces noise and repeated confirmation in large repos
+
+### MCP status and behavior
+
+| MCP status | Behavior |
+|----------|------|
+| CKB available | Enhanced mode: symbol-level impact/references/call graph/hotspots (`mcp__ckb__analyzeImpact`, `mcp__ckb__findReferences`, `mcp__ckb__getCallGraph`, `mcp__ckb__getHotspots`) |
+| CKB unavailable | Basic mode: Grep + Glob text search (full functionality, lower precision) |
+
+### Auto detection
+
+- Skills that depend on MCP call `mcp__ckb__getStatus` first (2s timeout)
+- Timeout/failure → silently falls back to basic mode (non-blocking)
+- No manual “basic/enhanced” switch required
+
+To enable enhanced mode: configure CKB per `../docs/推荐MCP.md` and run `/devbooks:index` to generate `index.scip`.
+
+</details>
+
+<details>
+<summary><strong>Proposal debate workflow</strong></summary>
+
+For strict proposal review, run the triangle debate:
+
+```
+/devbooks:debate
+```
+
+Three roles:
+1. **Author**: creates and defends the proposal
+2. **Challenger**: challenges assumptions, finds gaps, identifies risks
+3. **Judge**: makes the final decision and records rationale
+
+Decision: `Approved`, `Revise`, `Rejected`
+
+</details>
+
+---
+
+## Repository Structure
+
+```
+skills/                    # devbooks-* Skill sources (some ship scripts/)
+templates/                 # project init templates (used by `dev-playbooks-cn init`)
+templates/dev-playbooks/   # DevBooks protocol directory template (copied into your project as `dev-playbooks/`)
+scripts/                   # install & helper scripts
+docs/                      # documentation
+bin/                       # CLI entry
+```
+
+---
+
+## Documentation
+
+- [Slash command guide](../docs/Slash 命令使用指南.md)
+- [Skills guide](../skills/Skills使用说明.md)
+- [MCP configuration recommendations](../docs/推荐MCP.md)
+- [Integration template (protocol-agnostic)](../docs/DevBooks集成模板（协议无关）.md)
+- [Installation prompt](../docs/DevBooks安装提示词.md)
+
+---
+
+## License
+
+MIT

package/templates/dev-playbooks/changes/.gitkeep

@@ -0,0 +1 @@
+# DevBooks change packages

package/templates/dev-playbooks/constitution.md

@@ -0,0 +1,116 @@
+# 项目宪法 (Project Constitution)
+
+> 本文档定义项目的不可违背原则（Global Inviolable Principles）。
+> 所有 AI 助手和开发者在执行任何操作前必须遵守这些原则。
+
+---
+
+## Part Zero: 强制指令
+
+**在执行任何 Skill 或操作之前，必须：**
+
+1. 阅读并理解本宪法文档
+2. 确认操作不违反任何 GIP 原则
+3. 如有冲突，立即停止并报告
+
+---
+
+## 全局不可违背原则 (Global Inviolable Principles)
+
+### GIP-01: 角色隔离原则
+
+**规则**：Test Owner 与 Coder 必须在独立对话/独立实例中执行。
+
+**理由**：
+- 防止测试与实现之间的认知污染
+- 确保 Red-Green 循环的完整性
+- 避免"自己写测试自己改测试"的反模式
+
+**违规后果**：变更包不可归档。
+
+---
+
+### GIP-02: 测试不可篡改原则
+
+**规则**：Coder 角色禁止修改 `tests/**` 目录下的任何文件。
+
+**理由**：
+- 测试是规格的可执行形式
+- 修改测试等于修改规格，需要设计层面决策
+- 保证验收标准的独立性
+
+**例外**：如需修改测试，必须交还 Test Owner 处理。
+
+---
+
+### GIP-03: 设计优先原则
+
+**规则**：代码实现必须追溯到设计文档中的 AC-xxx。
+
+**理由**：
+- 确保所有代码变更有明确的业务目的
+- 支持全程追溯：设计 → 任务 → 测试 → 代码
+- 防止"幽灵功能"和无授权变更
+
+**验证方式**：`ac-trace-check.sh` 检查覆盖率。
+
+---
+
+### GIP-04: 真理源唯一原则
+
+**规则**：`specs/` 是系统行为的唯一真理源。
+
+**理由**：
+- 避免规格分散在多处导致不一致
+- 确保所有角色参考同一来源
+- 支持增量同步和冲突检测
+
+**操作约束**：
+- 变更包中的 spec delta 必须经过 stage → promote 流程
+- 禁止直接修改 `specs/` 目录
+
+---
+
+## 逃生舱口 (Escape Hatches)
+
+> 以下情况可临时绕过上述原则，但必须记录和追溯。
+
+### EH-01: 紧急修复
+
+**适用场景**：生产环境严重故障需要紧急修复。
+
+**流程**：
+1. 在 `evidence/` 中记录紧急修复原因
+2. 标记 `[EMERGENCY]` 前缀
+3. 事后补充完整的变更包
+
+### EH-02: 原型验证
+
+**适用场景**：技术方案不确定，需要快速验证。
+
+**约束**：
+- 代码必须放在 `prototype/` 目录
+- 禁止直接合入生产代码
+- 验证完成后通过正式流程提升
+
+### EH-03: 人工裁决
+
+**适用场景**：规则冲突或边缘情况需要人工判断。
+
+**流程**：
+1. 在 `proposal.md` 中记录决策点
+2. 由项目负责人签字确认
+3. 更新 Decision Log
+
+---
+
+## 宪法变更流程
+
+1. 任何对本宪法的修改必须通过正式的变更提案
+2. 变更提案需要经过 Challenger 质疑和 Judge 裁决
+3. 宪法变更的优先级为 P0，需要所有核心成员确认
+
+---
+
+**宪法版本**：v1.0.0
+**最后更新**：{{DATE}}

package/templates/dev-playbooks/project.md

@@ -0,0 +1,96 @@
+# 项目上下文 (Project Context)
+
+> 本文档描述项目的技术栈、约定和领域上下文。
+> 宪法性规则请参阅 `constitution.md`。
+
+---
+
+## 目的
+
+<!-- 在此描述你的项目目的 -->
+
+## 技术栈
+
+- **主语言**：<!-- 如 TypeScript, Python, Go -->
+- **框架**：<!-- 如 React, Django, Gin -->
+- **数据库**：<!-- 如 PostgreSQL, MongoDB -->
+- **配置格式**：YAML / JSON
+- **文档格式**：Markdown
+- **版本控制**：Git
+
+## 项目约定
+
+### 代码风格
+
+<!-- 描述你的代码风格要求 -->
+
+### 架构模式
+
+- **配置发现**：所有 Skills 通过 `config-discovery.sh` 发现配置
+- **宪法优先**：执行任何操作前加载 `constitution.md`
+- **三层同步**：Draft → Staged → Truth
+
+### 测试策略
+
+- **单元测试**：<!-- 如 Jest, pytest, go test -->
+- **覆盖率目标**：80%
+- **Red-Green 循环**：Test Owner 先产出 Red 基线，Coder 让其 Green
+
+### Git 工作流
+
+- **主分支**：`main` / `master`
+- **变更分支**：`change/<change-id>`
+- **提交格式**：`<type>: <subject>`
+  - type: feat, fix, refactor, docs, test, chore
+
+## 领域上下文
+
+### 核心概念
+
+| 术语 | 定义 |
+|------|------|
+| Truth Root | 真理源根目录，存放规格和设计的最终版本 |
+| Change Root | 变更包根目录，存放每次变更的所有产物 |
+| Spec Delta | 规格增量，描述变更对规格的修改 |
+| AC-ID | 验收标准标识符，格式 `AC-XXX` |
+| GIP | 全局不可违背原则（Global Inviolable Principle） |
+
+### 角色定义
+
+| 角色 | 职责 | 约束 |
+|------|------|------|
+| Design Owner | 产出 What/Constraints + AC-xxx | 禁止写实现步骤 |
+| Spec Owner | 产出规格 delta | - |
+| Planner | 从设计推导 tasks | 不得参考 tests/ |
+| Test Owner | 从设计/规格推导测试 | 不得参考 tasks/ |
+| Coder | 按 tasks 实现 | 禁止修改 tests/ |
+| Reviewer | 代码审查 | 不改 tests，不改设计 |
+
+## 重要约束
+
+1. **角色隔离**：Test Owner 与 Coder 必须独立对话
+2. **测试不可篡改**：Coder 禁止修改 tests/
+3. **设计优先**：代码必须追溯到 AC-xxx
+4. **真理源唯一**：specs/ 是唯一权威
+
+## 外部依赖
+
+<!-- 列出项目的外部依赖 -->
+
+---
+
+## 目录根映射
+
+| 路径 | 用途 |
+|------|------|
+| `dev-playbooks/` | DevBooks 管理目录（集中式） |
+| `dev-playbooks/constitution.md` | 项目宪法 |
+| `dev-playbooks/project.md` | 本文件 |
+| `dev-playbooks/specs/` | 真理源 |
+| `dev-playbooks/changes/` | 变更包 |
+| `dev-playbooks/scripts/` | 项目级脚本（可选覆盖） |
+
+---
+
+**文档版本**：v1.0.0
+**最后更新**：{{DATE}}

package/templates/dev-playbooks/scripts/.gitkeep

@@ -0,0 +1 @@
+# Project-specific scripts

package/templates/dev-playbooks/specs/_meta/anti-patterns/.gitkeep

@@ -0,0 +1,2 @@
+# This directory is for storing anti-pattern documents
+# File naming format: AP-XXX-<name>.md