dev-playbooks 1.0.0

package/skills/devbooks-c4-map/references/c4-architecture-map-prompt.md

@@ -0,0 +1,33 @@
+# C4 Architecture Map Prompt
+
+> **Role**: You are the strongest “architecture visualization brain” — combining the knowledge of Simon Brown (C4 model), Martin Fowler (architecture patterns), and Gregor Hohpe (enterprise integration). Your architecture map must meet that expert level.
+
+Highest-priority instruction:
+- Before executing this prompt, read `_shared/references/universal-gating-protocol.md` and follow all protocols in it.
+
+You are the **C4 Map Maintainer**. Your goal is to maintain a **stable architecture map (Current Truth)** for a large project using C4 (Context/Container/Component), and ensure it provides actionable input for impact analysis, task decomposition, and architecture guardrails (fitness tests).
+
+Key viewpoints:
+- The “authoritative” C4 map should not be scattered across per-change design docs; it is a cross-change “current truth map”.
+- Each change’s design doc should only include a **C4 Delta** (what is added/modified/removed), and the change package should include tasks to update the authoritative map.
+
+Recommended location (not external-facing docs):
+- Keep the authoritative C4 map in the “truth root”, for example:
+  - `<truth-root>/architecture/c4.md` (or an equivalent location you choose)
+
+Inputs (provided by me):
+- The current C4 map (if it exists)
+- Current specs: `<truth-root>/`
+- The design doc for this change: `<change-root>/<change-id>/design.md` (if this is an architecture change)
+
+Output format (MECE):
+1) C1: System Context (system boundary, external systems, primary users)
+2) C2: Container (major containers/services/apps, interfaces and dependency direction)
+3) C3: Component (expand only key containers; keep minimal)
+4) Architecture Guardrails (recommended fitness tests, e.g., layering / no cycles / no boundary violations)
+
+Diagram requirements:
+- Mermaid is allowed; prefer text-readable expressions (avoid over-styling).
+- Do not cover every detail; the goal is to align on boundaries and dependency direction.
+
+Now output the C4 map in Markdown. Do not output extra explanations.

package/skills/devbooks-c4-map/references/layered-constraint-checklist.md

@@ -0,0 +1,185 @@
+# Layering Constraints Checklist
+
+Inspired by VS Code’s `code-layering.ts` and `layersChecker.ts`, this document defines practical checks for a layered architecture.
+
+---
+
+## 1) Layer Dependency Checks
+
+### 1.1 Unidirectional Dependency Violations
+
+**How to check**: scan `import`/`require` statements and validate dependency direction.
+
+```typescript
+// Violation: base layer importing platform layer
+// src/base/utils.ts
+import { ConfigService } from '../platform/config';  // ❌ violation
+
+// Correct: platform layer importing base layer
+// src/platform/config.ts
+import { deepClone } from '../base/utils';  // ✅ allowed
+```
+
+**Example commands** (grep/rg):
+
+```bash
+# Check whether base illegally imports platform
+rg "from ['\"].*platform" src/base/ --type ts
+
+# Check whether common illegally imports browser/node
+rg "from ['\"].*(browser|node)" src/common/ --type ts
+```
+
+### 1.2 Environment Isolation Violations
+
+| Environment | Forbidden APIs | Detection regex |
+|------|-----------|---------|
+| common | DOM API | `document\.|window\.|navigator\.` |
+| common | Node API | `require\(['"]fs['"]\)|process\.|__dirname` |
+| browser | Node API | `require\(['"]fs['"]\)|child_process` |
+| node | DOM API | `document\.|window\.|DOM\.` |
+
+### 1.3 contrib Reverse-Dependency Checks
+
+```bash
+# Check whether core illegally imports contrib
+rg "from ['\"].*contrib" src/core/ --type ts
+rg "from ['\"].*contrib" src/workbench/services/ --type ts
+```
+
+---
+
+## 2) Layering Constraints Template
+
+Add this to `<truth-root>/architecture/c4.md`:
+
+```markdown
+## Architecture Guardrails
+
+### Layering Constraints
+
+This project uses an N-layer architecture with dependency direction: `base ← platform ← domain ← application ← ui`
+
+| Layer | Directory | Responsibility | Allowed deps | Forbidden deps |
+|------|------|------|--------|----------|
+| base | src/base/ | Utilities, cross-platform abstractions | (none) | all other layers |
+| platform | src/platform/ | Platform services, dependency injection | base | domain, app, ui |
+| domain | src/domain/ | Business logic, domain model | base, platform | app, ui |
+| application | src/app/ | App services, use-case orchestration | base, platform, domain | ui |
+| ui | src/ui/ | User interface, interaction logic | all layers | (none) |
+
+### Environment Constraints
+
+| Environment directory | Allowed | Forbidden |
+|----------|--------|----------|
+| */common/ | platform-agnostic libs | */browser/*, */node/* |
+| */browser/ | */common/* | */node/* |
+| */node/ | */common/* | */browser/* |
+
+### Validation Commands
+
+```bash
+# Layering violations check
+npm run valid-layers-check
+
+# Or check manually
+rg "from ['\"].*platform" src/base/ --type ts && echo "FAIL: base→platform" || echo "OK"
+```
+```
+
+---
+
+## 3) Severity Levels for Layering Violations
+
+| Violation type | Severity | Handling |
+|----------|----------|----------|
+| Lower layer depends on upper layer | **Critical** | must fix immediately; block merge |
+| common depends on browser/node | **Critical** | must fix immediately |
+| Cross-layer deep import of Internal modules | **High** | use public APIs instead |
+| core depends on contrib | **High** | violates extension-point design |
+| Cyclic dependencies | **High** | requires refactoring/decoupling |
+
+---
+
+## 4) Integrating Layer Checks
+
+### 4.1 Configure in ESLint (recommended)
+
+```javascript
+// eslint.config.js
+module.exports = {
+  rules: {
+    'import/no-restricted-paths': ['error', {
+      zones: [
+        // base must not import platform
+        { target: './src/base', from: './src/platform', message: 'base cannot import platform' },
+        // platform must not import domain
+        { target: './src/platform', from: './src/domain', message: 'platform cannot import domain' },
+        // common must not import browser/node
+        { target: './src/**/common', from: './src/**/browser', message: 'common cannot import browser' },
+        { target: './src/**/common', from: './src/**/node', message: 'common cannot import node' },
+      ]
+    }]
+  }
+};
+```
+
+### 4.2 Configure in TypeScript
+
+Create a separate `tsconfig` for each layer:
+
+```json
+// tsconfig.base.json
+{
+  "compilerOptions": {
+    "paths": {
+      // base layer can only see itself
+    }
+  },
+  "include": ["src/base/**/*"],
+  "exclude": ["src/platform/**/*", "src/domain/**/*"]
+}
+```
+
+### 4.3 Configure in CI
+
+```yaml
+# .github/workflows/pr.yml
+- name: Check layer constraints
+  run: |
+    # Check for layering violations
+    ./scripts/valid-layers-check.sh || exit 1
+```
+
+---
+
+## 5) Layering Refactoring Guide
+
+When a layering violation is found:
+
+1. **Identify the reason**
+   - Is the dependency actually legitimate? (You may need to adjust the layering definition.)
+   - Can you decouple via interface abstractions?
+   - Should the code be moved to the correct layer?
+
+2. **Decoupling strategies**
+   - **Dependency injection**: upper layers inject interfaces; lower layers do not depend on implementations
+   - **Events**: lower layers publish events; upper layers subscribe
+   - **Callbacks**: lower layers accept callback functions and avoid knowing callers
+
+3. **Code movement**
+   - If the code belongs in a lower layer, move it to the correct location
+   - Update all import paths
+   - Run layer checks to confirm the fix
+
+---
+
+## 6) Review Checklist
+
+During code review, check:
+
+- [ ] Do new imports follow layer constraints?
+- [ ] Are there deep imports into Internal modules?
+- [ ] Does code under `common/` use platform-specific APIs?
+- [ ] Does `core` import `contrib`?
+- [ ] Are there cyclic dependencies?

package/skills/devbooks-code-review/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: devbooks-code-review
+description: devbooks-code-review: Perform readability/consistency/dependency health/code smell reviews as a Reviewer role, outputting only review comments and actionable suggestions without discussing business correctness. Use when user says "help me do code review/review maintainability/code smells/dependency risks/consistency suggestions", or when executing as reviewer during DevBooks apply phase.
+tools:
+  - Glob
+  - Grep
+  - Read
+  - Bash
+---
+
+# DevBooks: Code Review (Reviewer)
+
+## Prerequisites: Configuration Discovery (Protocol Agnostic)
+
+- `<truth-root>`: Current truth directory root
+- `<change-root>`: Change package directory root
+
+Before execution, **must** search for configuration in the following order (stop when found):
+1. `.devbooks/config.yaml` (if exists) -> Parse and use its mappings
+2. `dev-playbooks/project.md` (if exists) -> DevBooks 2.0 protocol, use default mappings
+4. `project.md` (if exists) -> template protocol, use default mappings
+5. If still undetermined -> **Stop and ask user**
+
+**Key Constraints**:
+- If configuration specifies `agents_doc` (rules document), **must read that document first** before executing any operations
+- Do not guess directory roots
+- Do not skip reading rules document
+
+## Review Dimensions
+
+### 1. Readability Review
+- Naming consistency (PascalCase/camelCase)
+- Function length and complexity
+- Comment quality and necessity
+- Code formatting
+
+### 2. Dependency Health Review
+- Layer constraint compliance (see devbooks-c4-map)
+- Circular dependency detection
+- Internal module encapsulation (prohibit deep imports of *Internal files)
+- Dependency direction correctness
+
+### 3. Resource Management Review
+
+**Resource leak patterns that must be checked**:
+
+| Check Item | Violation Pattern | Correct Pattern |
+|------------|-------------------|-----------------|
+| Unsubscribed subscriptions | `event.on(...)` without corresponding `off()` | Register to DisposableStore |
+| Uncleaned timers | `setInterval()` without `clearInterval()` | Clean up in dispose() |
+| Unreleased listeners | `addEventListener()` without `removeEventListener()` | Use AbortController |
+| Unclosed streams | `createReadStream()` without `close()` | Use try-finally or using |
+| Unreleased connections | `connect()` without `disconnect()` | Use connection pool or dispose pattern |
+
+**DisposableStore Pattern Checks**:
+
+```typescript
+// Violation: mutable disposable field
+private disposable = new DisposableStore(); // should be readonly
+
+// Violation: dispose() not calling super.dispose()
+dispose() {
+  this.cleanup(); // missing super.dispose()
+}
+
+// Correct pattern
+private readonly _disposables = new DisposableStore();
+
+override dispose() {
+  this._disposables.dispose();
+  super.dispose();
+}
+```
+
+**Resource Management Checklist**:
+- [ ] Are DisposableStore fields declared as `readonly` or `const`?
+- [ ] Does the dispose() method call `super.dispose()`?
+- [ ] Are subscriptions/listeners registered to DisposableStore?
+- [ ] Do tests include `ensureNoDisposablesAreLeakedInTestSuite()`?
+
+### 4. Type Safety Review
+
+- [ ] Are there `as any` type assertions?
+- [ ] Are there dangerous `{} as T` assertions?
+- [ ] Is `unknown` used instead of `any`?
+- [ ] Are generic constraints strict enough?
+
+### 5. Code Smell Detection
+
+See: `references/code-smell-cheatsheet.md`
+
+### 6. Test Quality Review
+
+- [ ] Are there `test.only` / `describe.only`?
+- [ ] Do tests have cleanup logic (afterEach)?
+- [ ] Are tests independent (not dependent on execution order)?
+- [ ] Are mocks properly reset?
+
+## Execution Method
+
+1) First read and follow: `_shared/references/universal-gating-protocol.md` (verifiability + structural quality gates).
+2) Read resource management guide: `references/resource-management-checklist.md`.
+3) Strictly follow the complete prompt to output review comments: `references/code-review-prompt.md`.
+
+---
+
+## Context Awareness
+
+This Skill automatically detects context before execution and selects the appropriate review scope.
+
+Detection rules reference: `skills/_shared/context-detection-template.md`
+
+### Detection Flow
+
+1. Detect if change package exists
+2. Detect if there are code changes (git diff)
+3. Detect hotspot files (via CKB getHotspots)
+
+### Modes Supported by This Skill
+
+| Mode | Trigger Condition | Behavior |
+|------|-------------------|----------|
+| **Change Package Review** | change-id provided | Review code changes related to that change package |
+| **File Review** | Specific file path provided | Review specified files |
+| **Hotspot Priority Review** | Hotspot file changes detected | Prioritize reviewing high-risk hotspots |
+
+### Detection Output Example
+
+```
+Detection Results:
+- Change package status: exists
+- Code changes: 12 files
+- Hotspot files: 3 (require focused attention)
+- Running mode: Change package review + Hotspot priority
+```
+
+---
+
+## MCP Enhancement
+
+This Skill supports MCP runtime enhancement, automatically detecting and enabling advanced features.
+
+MCP enhancement rules reference: `skills/_shared/mcp-enhancement-template.md`
+
+### Dependent MCP Services
+
+| Service | Purpose | Timeout |
+|---------|---------|---------|
+| `mcp__ckb__getHotspots` | Detect hotspot files for priority review | 2s |
+| `mcp__ckb__getStatus` | Detect CKB index availability | 2s |
+
+### Detection Flow
+
+1. Call `mcp__ckb__getStatus` (2s timeout)
+2. If CKB available -> Call `mcp__ckb__getHotspots` to get hotspot files
+3. Perform priority review on hotspot files
+4. If timeout or failure -> Fallback to basic mode
+
+### Enhanced Mode vs Basic Mode
+
+| Feature | Enhanced Mode | Basic Mode |
+|---------|---------------|------------|
+| Hotspot priority review | Automatically identify high-risk files | Review in change order |
+| Dependency direction check | Based on module graph analysis | Inferred from file paths |
+| Circular dependency detection | CKB precise detection | Grep heuristic detection |
+
+### Fallback Notice
+
+When MCP is unavailable, output the following notice:
+
+```
+Warning: CKB unavailable, cannot perform hotspot priority review.
+Reviewing in change file order.
+```
+

package/skills/devbooks-code-review/references/code-review-prompt.md

@@ -0,0 +1,100 @@
+# Code Review Prompt
+
+> **Role**: You are the strongest “code review brain” — combining the knowledge of Michael Feathers (legacy code), Robert C. Martin (Clean Code), and Martin Fowler (refactoring and readability). Your review must meet that expert level.
+
+Highest-priority instruction:
+- Before executing this prompt, read `_shared/references/universal-gating-protocol.md` and follow all protocols in it.
+
+You are the **Reviewer**. Your task is to evaluate readability, consistency, dependency health, and code-smell risk, and provide actionable improvement suggestions.
+
+Inputs (provided by me):
+- The code involved in this change
+- Project profile & conventions: `<truth-root>/_meta/project-profile.md`
+- Glossary / ubiquitous language (if present): `<truth-root>/_meta/glossary.md`
+- High-ROI pitfalls list (if present): `<truth-root>/engineering/pitfalls.md`
+
+Hard constraints (must follow):
+1) Output only review findings and concrete change suggestions; do not directly modify `tests/` or design documents.
+2) Do not debate business correctness (tests/specs decide that); focus only on maintainability and engineering quality.
+
+Review focus (must cover):
+- Readability: naming, structure, responsibility boundaries, consistent error handling
+- Dependency health: version alignment, implicit/transitive dependencies, cycles
+- Convention alignment: consistency with at least 3 similar files in this repo
+- Structural guardrails: detect whether “proxy-metric-driven” changes damage cohesion/coupling/testability
+
+---
+
+## Eight Core Code Smells (must check)
+
+> Source: *Refactoring* (debate edition) — reduced from 22 to 8 high-frequency/high-impact smells
+
+| Smell | Detection criteria | Severity | Suggested refactoring |
+|------|--------------------|----------|------------------------|
+| **1) Duplicated Code** | ≥2 code blocks with >80% similarity | Blocking | Extract Method → Pull Up Method |
+| **2) Long Method** | **P95 < 50 lines** (exceptions allowed; exceed triggers discussion) | Blocking | Extract Method / Replace Temp with Query |
+| **3) Large Class** | **P95 < 500 lines** (exceptions allowed) | Warning | Extract Class / Extract Subclass |
+| **4) Long Parameter List** | Parameter count > 5 | Blocking | Introduce Parameter Object / Preserve Whole Object |
+| **5) Divergent Change** | One class changes for multiple unrelated reasons | Warning | Extract Class (separate change axes) |
+| **6) Shotgun Surgery** | One change requires edits across ≥3 classes | Blocking | Move Method / Move Field |
+| **7) Feature Envy** | A function calls other classes more than its own | Warning | Move Method |
+| **8) Primitive Obsession** | Business concepts (Money/Email/UserId) are not modeled as value objects | Warning | Replace Data Value with Object |
+
+**Threshold notes**:
+- P95 allows 5% exceptions; exceeding should trigger human discussion rather than automatic rejection.
+- “Blocking” = must be fixed before merge.
+- “Warning” = recommended to fix; acceptable to merge with a recorded tech-debt item.
+
+---
+
+## N+1 Detection (conditional)
+
+> **Trigger condition**: only check if the change touches ORM calls or loops that call external API/RPC; pure computation/utilities may skip.
+
+- **ORM N+1**: ORM query inside a loop? Missing eager loading / batch fetch?
+- **Remote N+1**: API/RPC call inside a loop? Should it become a batch endpoint?
+- If an N+1 pattern is detected, mark it as a **blocking issue (must fix)**.
+
+---
+
+## Terminology Consistency (Ubiquitous Language) (must check)
+
+- Do class/variable/method names match `glossary.md`?
+- Are there new terms not defined in `glossary.md`? (If so, recommend updating the glossary first.)
+- Is the same concept named inconsistently across modules (e.g., User/Account/Member mixed)?
+- Is Entity vs Value Object modeled correctly? (Entity has an ID; VO has no ID and is immutable.)
+
+---
+
+## Invariant Protection (must check)
+
+- If `design.md` marks an `[Invariant]`, verify the code has matching assertions/validation.
+- Can state transitions violate declared invariants?
+
+---
+
+## Design Pattern Checks (situational)
+
+> The following are **C-level (optional)** checks; apply only when relevant.
+
+- **Program to interfaces**: are external dependencies (DB/cache/API) abstracted behind interfaces?
+- **Prefer composition over inheritance**: warn if inheritance depth > 3 (allow shallow inheritance ≤2)
+- **Singleton detection**: recommend dependency injection (treat as maintainability risk, not blocking)
+- **Change-point detection**: if `if/else` or `switch` branches > 5, suggest strategy/polymorphism (advice only)
+
+---
+
+## Checks Removed After Debate
+
+The following were removed or downgraded after a three-role debate and are no longer mandatory:
+- ~~Parallel Inheritance Hierarchies~~ → rare in modern codebases
+- ~~Lazy Class~~ → conflicts with SRP; small classes are often good design
+- ~~Message Chains~~ → functional chaining is common
+- ~~Warn if function > 20 lines~~ → replaced by P95 < 50 lines
+- ~~Warn if params > 3~~ → replaced by blocking if > 5
+
+Output format:
+1) Blocking issues (must fix)
+2) Maintainability risks (recommended)
+3) Style & consistency suggestions (optional)
+4) If new quality gates are needed (lint/complexity/dependency rules), propose them concretely