dev-playbooks 1.0.0

package/skills/devbooks-federation/scripts/federation-check.sh

@@ -0,0 +1,144 @@
+#!/bin/bash
+# DevBooks federation check script
+# Purpose: detect whether changes touch federation contracts and generate an impact report
+
+set -e
+
+# Color output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+echo_info() { echo -e "${GREEN}[Federation]${NC} $1"; }
+echo_warn() { echo -e "${YELLOW}[Federation]${NC} $1"; }
+echo_error() { echo -e "${RED}[Federation]${NC} $1"; }
+
+# Argument parsing
+PROJECT_ROOT="."
+CHANGE_FILES=""
+OUTPUT=""
+QUIET=false
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --project-root) PROJECT_ROOT="$2"; shift 2 ;;
+        --change-files) CHANGE_FILES="$2"; shift 2 ;;
+        --output) OUTPUT="$2"; shift 2 ;;
+        --quiet) QUIET=true; shift ;;
+        -h|--help)
+            echo "usage: federation-check.sh [options]"
+            echo ""
+            echo "Options:"
+            echo "  --project-root <dir>   Project root (default: .)"
+            echo "  --change-files <list>  Changed files (comma-separated)"
+            echo "  --output <file>        Output report path"
+            echo "  --quiet                Quiet mode"
+            exit 0
+            ;;
+        *) echo_error "Unknown argument: $1"; exit 1 ;;
+    esac
+done
+
+cd "$PROJECT_ROOT"
+
+# Find federation config
+FEDERATION_CONFIG=""
+if [ -f ".devbooks/federation.yaml" ]; then
+    FEDERATION_CONFIG=".devbooks/federation.yaml"
+elif [ -f "dev-playbooks/federation.yaml" ]; then
+    FEDERATION_CONFIG="dev-playbooks/federation.yaml"
+fi
+
+if [ -z "$FEDERATION_CONFIG" ]; then
+    [ "$QUIET" = false ] && echo_info "No federation config found; skipping"
+    exit 0
+fi
+
+[ "$QUIET" = false ] && echo_info "Using federation config: $FEDERATION_CONFIG"
+
+# If no changed files were provided, try to read them from git
+if [ -z "$CHANGE_FILES" ]; then
+    if [ -d ".git" ]; then
+        CHANGE_FILES=$(git diff --cached --name-only 2>/dev/null | tr '\n' ',' | sed 's/,$//')
+        if [ -z "$CHANGE_FILES" ]; then
+            CHANGE_FILES=$(git diff --name-only HEAD~1 2>/dev/null | tr '\n' ',' | sed 's/,$//')
+        fi
+    fi
+fi
+
+if [ -z "$CHANGE_FILES" ]; then
+    [ "$QUIET" = false ] && echo_info "No changed files; skipping"
+    exit 0
+fi
+
+[ "$QUIET" = false ] && echo_info "Checking changed files: $CHANGE_FILES"
+
+# Extract contract patterns (simple implementation: parse contracts lines from YAML)
+CONTRACT_PATTERNS=$(grep -E "^\s+-\s+\"" "$FEDERATION_CONFIG" 2>/dev/null | sed 's/.*"\([^"]*\)".*/\1/' | tr '\n' '|' | sed 's/|$//')
+
+if [ -z "$CONTRACT_PATTERNS" ]; then
+    [ "$QUIET" = false ] && echo_info "No contract patterns defined; skipping"
+    exit 0
+fi
+
+# Detect whether changes touch contracts
+CONTRACT_CHANGES=""
+IFS=',' read -ra FILES <<< "$CHANGE_FILES"
+for file in "${FILES[@]}"; do
+    if echo "$file" | grep -qE "$CONTRACT_PATTERNS"; then
+        CONTRACT_CHANGES="$CONTRACT_CHANGES$file,"
+    fi
+done
+CONTRACT_CHANGES=${CONTRACT_CHANGES%,}
+
+if [ -z "$CONTRACT_CHANGES" ]; then
+    [ "$QUIET" = false ] && echo_info "No contract files changed"
+    exit 0
+fi
+
+# Contract changes found
+echo_warn "Contract changes detected: $CONTRACT_CHANGES"
+
+# Generate report
+REPORT=$(cat << EOF
+# Cross-repository impact analysis report
+
+> Auto-generated on $(date +%Y-%m-%d)
+> Federation config: $FEDERATION_CONFIG
+
+## Contract changes
+
+The following files match federation contracts:
+
+$(echo "$CONTRACT_CHANGES" | tr ',' '\n' | while read f; do echo "- \`$f\`"; done)
+
+## Recommended actions
+
+1. [ ] Confirm change type (Breaking / Deprecation / Enhancement / Patch)
+2. [ ] Run \`devbooks-federation\` for full cross-repo impact analysis
+3. [ ] If breaking, notify downstream consumers
+4. [ ] Update CHANGELOG
+
+## Downstream consumers
+
+$(grep -A20 "downstreams:" "$FEDERATION_CONFIG" 2>/dev/null | grep -E "^\s+-\s+name:" | sed 's/.*name:\s*"\([^"]*\)".*/- \1/' || echo "(see federation.yaml)")
+
+---
+
+> Tip: use the \`devbooks-federation\` skill for full analysis
+EOF
+)
+
+# Output report
+if [ -n "$OUTPUT" ]; then
+    echo "$REPORT" > "$OUTPUT"
+    echo_info "Report generated: $OUTPUT"
+else
+    echo ""
+    echo "$REPORT"
+fi
+
+# Return non-zero to indicate contract changes
+exit 1

package/skills/devbooks-federation/templates/federation.yaml

@@ -0,0 +1,89 @@
+# DevBooks cross-repo federation config template
+# Purpose: define multi-repo dependencies and impact-analysis boundaries
+#
+# Install:
+#   cp this-file .devbooks/federation.yaml
+#   # or
+#   cp this-file dev-playbooks/federation.yaml
+#
+# Usage:
+#   - devbooks-impact-analysis auto-detects this file and analyzes cross-repo boundaries
+#   - guardrail-check.sh --check-federation verifies federation constraints
+
+# Federation config version
+version: "1.0"
+
+# Current repository info
+current:
+  name: "my-service"
+  type: "service"  # service | library | shared | monorepo-package
+  owner: "team-a"
+
+# Upstream dependencies (repos this repo depends on)
+upstreams:
+  - name: "shared-types"
+    repo: "org/shared-types"
+    # Optional: specify the exact modules/APIs depended on
+    contracts:
+      - "src/types/user.ts"
+      - "src/types/order.ts"
+    # Version constraint
+    version: "^2.0.0"
+    # Change notification
+    notify_on_change: true
+
+  - name: "auth-sdk"
+    repo: "org/auth-sdk"
+    contracts:
+      - "src/client.ts"
+    version: ">=1.5.0"
+
+# Downstream consumers (repos that depend on this repo)
+downstreams:
+  - name: "web-app"
+    repo: "org/web-app"
+    # Contracts exposed to this consumer
+    contracts:
+      - "src/api/v1/**"
+      - "src/events/published.ts"
+
+  - name: "mobile-app"
+    repo: "org/mobile-app"
+    contracts:
+      - "src/api/v1/**"
+
+# Federation rules
+rules:
+  # Contract change rules
+  contract_change:
+    # Change types that must notify downstream consumers
+    notify_types:
+      - breaking    # breaking changes
+      - deprecation # deprecation notices
+    # Notification channels
+    notify_channels:
+      - github_issue  # create an issue in downstream repos
+      - slack         # send Slack notification (requires webhook)
+
+  # Version compatibility
+  compatibility:
+    # Minimum number of prior versions to support
+    min_supported_versions: 2
+    # Minimum days from deprecation to removal
+    deprecation_period_days: 30
+
+  # Impact analysis boundary
+  impact_analysis:
+    # Max analysis depth (how many repos deep)
+    max_depth: 2
+    # Whether to include test code
+    include_tests: false
+
+# Local development (optional)
+local_dev:
+  # Local repository path mapping
+  paths:
+    shared-types: "../shared-types"
+    auth-sdk: "../auth-sdk"
+  # Whether to use local linking
+  use_local_links: true

package/skills/devbooks-impact-analysis/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: devbooks-impact-analysis
+description: devbooks-impact-analysis: Performs impact analysis before cross-module/cross-file/external contract changes, producing the Impact section (Scope/Impacts/Risks/Minimal Diff/Open Questions) that can be directly written to proposal.md. Use when the user mentions "impact analysis/change scope control/reference lookup/affected modules/compatibility risks" etc.
+tools:
+  - Glob
+  - Grep
+  - Read
+  - Bash
+---
+
+# DevBooks: Impact Analysis
+
+## 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 the mappings within
+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 unable to determine -> **Stop and ask the user**
+
+**Key Constraints**:
+- If `agents_doc` (rules document) is specified in the configuration, **must read that document first** before performing any operations
+- Do not guess directory roots
+- Do not skip reading the rules document
+
+## Output Location
+
+- Recommended: Write to the Impact section of `<change-root>/<change-id>/proposal.md` (or create a separate analysis document and backfill later)
+
+## Execution Method
+
+1) First read and follow: `_shared/references/universal-gating-protocol.md` (Verifiability + Structural Quality Gate).
+2) Use `Grep` to search for symbol references, `Glob` to find related files.
+3) Strictly follow the complete prompt to output Impact Analysis Markdown: `references/impact-analysis-prompt.md`.
+
+## Output Format
+
+```markdown
+## Impact Analysis
+
+### Scope
+- Direct impact: X files
+- Indirect impact: Y files
+
+### Impacts
+| File | Impact Type | Risk Level |
+|------|-------------|------------|
+| ... | Direct call | High |
+
+### Risks
+- ...
+
+### Minimal Diff
+- ...
+
+### Open Questions
+- ...
+```
+
+---
+
+## Context Awareness
+
+This Skill automatically detects context before execution and selects the appropriate analysis scope.
+
+Detection rules reference: `skills/_shared/context-detection-template.md`
+
+### Detection Flow
+
+1. Detect whether a change package exists
+2. Detect whether the `proposal.md` already has an Impact section
+3. Detect whether CKB index is available (enhances analysis capability)
+
+### Modes Supported by This Skill
+
+| Mode | Trigger Condition | Behavior |
+|------|-------------------|----------|
+| **New Analysis** | Impact section does not exist | Perform complete impact analysis |
+| **Incremental Analysis** | Impact exists, new changes present | Update affected files list |
+| **Enhanced Analysis** | CKB index available | Use call graph for precise analysis |
+| **Basic Analysis** | CKB index unavailable | Use Grep text search for analysis |
+
+### Detection Output Example
+
+```
+Detection Results:
+- proposal.md: Exists, Impact section missing
+- CKB Index: Available
+- Run Mode: New Analysis + Enhanced Mode
+```
+
+---
+
+## MCP Enhancement
+
+This Skill supports MCP runtime enhancement, automatically detecting and enabling advanced features.
+
+MCP enhancement rules reference: `skills/_shared/mcp-enhancement-template.md`
+
+### Required MCP Services
+
+| Service | Purpose | Timeout |
+|---------|---------|---------|
+| `mcp__ckb__analyzeImpact` | Symbol-level impact analysis | 2s |
+| `mcp__ckb__findReferences` | Precise reference lookup | 2s |
+| `mcp__ckb__getCallGraph` | Call graph analysis | 2s |
+| `mcp__ckb__getStatus` | Detect CKB index availability | 2s |
+
+### Detection Flow
+
+1. Call `mcp__ckb__getStatus` (2s timeout)
+2. If CKB available -> Use `analyzeImpact` and `findReferences` for precise analysis
+3. If timeout or failure -> Fallback to basic mode (Grep text search)
+
+### Enhanced Mode vs Basic Mode
+
+| Feature | Enhanced Mode | Basic Mode |
+|---------|---------------|------------|
+| Reference Lookup | Symbol-level precise matching | Text Grep search |
+| Impact Scope | Call graph transitive analysis | Direct reference counting |
+| Risk Assessment | Quantified based on call depth | Estimated based on file count |
+| Cross-module Analysis | Automatic module boundary recognition | Requires manual scope specification |
+
+### Fallback Notice
+
+When MCP is unavailable, output the following notice:
+
+```
+Warning: CKB unavailable, using Grep text search for impact analysis.
+Analysis results may not be precise. Recommend running /devbooks:index to generate index and re-analyze.
+```
+

package/skills/devbooks-impact-analysis/references/impact-analysis-prompt.md

@@ -0,0 +1,82 @@
+# Impact Analysis Prompt
+
+> **Role**: You are the strongest mind in system analysis, combining the wisdom of Michael Feathers (dependency analysis and legacy code), Sam Newman (service boundaries and impact control), and Martin Fowler (refactoring risk assessment). Your analysis must meet expert-level standards.
+
+Highest directive (top priority):
+- Before executing this prompt, read `_shared/references/universal-gating-protocol.md` and follow all protocols within it.
+
+You are the "Impact Analyst." Your goal is to produce an **actionable impact analysis and change-scope control** before any cross-module/cross-file change, reducing consistency errors and omissions in large projects.
+
+Applicable scenarios:
+- Refactoring, cross-module changes, external interface/data contract changes, architecture boundary adjustments
+- You have semantic indexing/impact analysis capability (e.g., CKB/CodeMCP), or at least LSP/reference lookup capability
+
+Input materials (provided by me):
+- Change intent (1–3 sentences)
+- Design doc (if any): `<change-root>/<change-id>/design.md`
+- Current truth source: `<truth-root>/`
+- Codebase (read-only analysis)
+
+Hard constraints (must follow):
+- Impact analysis first, code later
+- No "decorative/surface refactors" unless they directly reduce risk for this change
+- Output must be directly usable in the Impact section of `proposal.md`
+
+Tool priority:
+1) Semantic index/impact analysis (preferred): references, call chains, dependency chains, impacted symbols/modules
+2) LSP: references/definitions/type diagnostics
+3) Degraded fallback: `rg` full-text search (must state lower confidence)
+
+Output format (MECE):
+1) Scope
+   - In / Out
+2) **Change Type Classification** (new, required):
+   - Based on GoF "8 causes of redesign," mark which category/categories this change falls into:
+   - [ ] **Specific class creation**: objects created by explicit class names (should move to factory/abstract factory)
+   - [ ] **Algorithm dependency**: depends on a specific algorithm implementation (should be encapsulated via strategy)
+   - [ ] **Platform dependency**: depends on specific hardware/OS/external platform (should be isolated via abstract factory/bridge)
+   - [ ] **Representation/implementation dependency**: depends on internal object structure (should isolate via interface)
+   - [ ] **Feature extension**: new features/operations needed (design extension points rather than modify core)
+   - [ ] **Object responsibility change**: object responsibilities are changing (check single-responsibility violation)
+   - [ ] **Subsystem/module replacement**: entire subsystem replacement (must have clear module boundaries)
+   - [ ] **Interface contract change**: external interface changes (must have versioning strategy)
+   - **Notation**: check applicable items and briefly state the impact scope
+3) Impacts
+   - A. External contracts (API/events/schema)
+   - B. Data and migration (DB/replay/idempotency)
+   - C. Modules and dependencies (boundaries/call direction/cycle risk)
+   - D. Tests and verification (anchors to add/update; snapshot tests prioritized for refactor/migration)
+   - **E. Bounded Context boundaries** (new, required):
+     - Does this change cross Bounded Contexts?
+     - If cross-context: do we need to introduce or update ACL (Anti-Corruption Layer)?
+     - ACL checklist:
+       - Are external system/API changes isolated by ACL? (External model changes must not leak into internal models)
+       - Are there direct calls to external APIs bypassing the adapter layer?
+       - If adding external dependency: suggested ACL interface definition
+4) Compatibility and Risks
+   - Breaking changes (explicitly mark if any)
+   - Migration/rollback paths
+5) Minimal Diff Strategy
+   - Preferred change points (1–3 "convergence points")
+   - Explicitly forbidden change types (avoid scope creep)
+6) **Pinch Point Identification and Minimal Test Set** (new, required)
+   - **Pinch Point definition**: nodes where multiple call paths converge; tests here cover all downstream paths
+   - **Identification method**:
+     - Analyze call chains to find "many-in-one-out" convergence points
+     - Prefer: public interfaces, service entry points, data transformation layers, event handlers
+     - Tool assist: `LSP findReferences` -> functions/classes called from multiple places
+   - **Output format**:
+     ```
+     Pinch Points:
+     - [PP-1] `OrderService.processOrder()` - 3 call paths converge
+     - [PP-2] `PaymentGateway.execute()` - 2 call paths converge
+
+     Minimal test set:
+     - 1 test at PP-1 -> covers OrderController/BatchProcessor/EventHandler
+     - 1 test at PP-2 -> covers CheckoutFlow/RefundFlow
+     - Estimated tests: 2 (instead of 5 per path)
+     ```
+   - **ROI principle**: test count equals pinch point count, not call path count
+7) Open Questions (<= 3)
+
+Start the impact analysis in Markdown now; do not output extra explanations.

package/skills/devbooks-impact-analysis/scripts/graph-cache.sh

@@ -0,0 +1,214 @@
+#!/bin/bash
+# DevBooks graph cache manager
+# Purpose: cache common CKB MCP query results to reduce repeated queries
+
+set -e
+
+CACHE_DIR=".devbooks/cache/graph"
+CACHE_TTL=3600  # default TTL: 1 hour (seconds)
+
+# Color output
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+echo_info() { echo -e "${GREEN}[Cache]${NC} $1"; }
+echo_warn() { echo -e "${YELLOW}[Cache]${NC} $1"; }
+
+# Argument parsing
+ACTION=""
+KEY=""
+VALUE=""
+TTL=$CACHE_TTL
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        get|set|clear|status|warm) ACTION="$1"; shift ;;
+        --key) KEY="$2"; shift 2 ;;
+        --value) VALUE="$2"; shift 2 ;;
+        --ttl) TTL="$2"; shift 2 ;;
+        --project-root) cd "$2"; shift 2 ;;
+        -h|--help)
+            echo "usage: graph-cache.sh <action> [options]"
+            echo ""
+            echo "Actions:"
+            echo "  get     Get cache"
+            echo "  set     Set cache"
+            echo "  clear   Clear cache"
+            echo "  status  Show cache status"
+            echo "  warm    Warm cache"
+            echo ""
+            echo "Options:"
+            echo "  --key <name>      Cache key"
+            echo "  --value <data>    Cache value"
+            echo "  --ttl <seconds>   Cache TTL (default: 3600)"
+            echo "  --project-root    Project root"
+            exit 0
+            ;;
+        *) shift ;;
+    esac
+done
+
+# Ensure cache directory exists
+mkdir -p "$CACHE_DIR"
+
+# Compute cache file path
+get_cache_file() {
+    local key="$1"
+    local hash=$(echo "$key" | md5sum | cut -d' ' -f1)
+    echo "$CACHE_DIR/${hash}.json"
+}
+
+# Check whether cache is valid
+is_cache_valid() {
+    local cache_file="$1"
+    local ttl="${2:-$CACHE_TTL}"
+
+    if [ ! -f "$cache_file" ]; then
+        return 1
+    fi
+
+    local file_age=$(( $(date +%s) - $(stat -f%m "$cache_file" 2>/dev/null || stat -c%Y "$cache_file" 2>/dev/null) ))
+
+    if [ $file_age -gt $ttl ]; then
+        return 1
+    fi
+
+    return 0
+}
+
+# Get cache
+cache_get() {
+    local cache_file=$(get_cache_file "$KEY")
+
+    if is_cache_valid "$cache_file" "$TTL"; then
+        cat "$cache_file"
+        return 0
+    else
+        return 1
+    fi
+}
+
+# Set cache
+cache_set() {
+    local cache_file=$(get_cache_file "$KEY")
+
+    # Write cache metadata
+    cat > "$cache_file" << EOF
+{
+  "key": "$KEY",
+  "timestamp": $(date +%s),
+  "ttl": $TTL,
+  "data": $VALUE
+}
+EOF
+
+    echo_info "cached: $KEY"
+}
+
+# Clear cache
+cache_clear() {
+    if [ -n "$KEY" ]; then
+        local cache_file=$(get_cache_file "$KEY")
+        rm -f "$cache_file"
+        echo_info "cleared: $KEY"
+    else
+        rm -rf "$CACHE_DIR"/*
+        echo_info "cleared all cache entries"
+    fi
+}
+
+# Show cache status
+cache_status() {
+    echo "=== DevBooks graph cache status ==="
+    echo ""
+
+    if [ ! -d "$CACHE_DIR" ] || [ -z "$(ls -A "$CACHE_DIR" 2>/dev/null)" ]; then
+        echo "cache is empty"
+        return
+    fi
+
+    local total=0
+    local valid=0
+    local expired=0
+
+    echo "| Key | Size | Age | Status |"
+    echo "|-----|------|------|------|"
+
+    for cache_file in "$CACHE_DIR"/*.json; do
+        if [ -f "$cache_file" ]; then
+            total=$((total + 1))
+
+            local size=$(du -h "$cache_file" | cut -f1)
+            local age=$(( ($(date +%s) - $(stat -f%m "$cache_file" 2>/dev/null || stat -c%Y "$cache_file" 2>/dev/null)) ))
+            local age_min=$((age / 60))
+
+            local key=$(jq -r '.key // "unknown"' "$cache_file" 2>/dev/null || echo "unknown")
+            local ttl=$(jq -r '.ttl // 3600' "$cache_file" 2>/dev/null || echo 3600)
+
+            local status="✅ valid"
+            if [ $age -gt $ttl ]; then
+                status="❌ expired"
+                expired=$((expired + 1))
+            else
+                valid=$((valid + 1))
+            fi
+
+            # Truncate long keys
+            if [ ${#key} -gt 30 ]; then
+                key="${key:0:27}..."
+            fi
+
+            echo "| $key | $size | ${age_min}m | $status |"
+        fi
+    done
+
+    echo ""
+    echo "total: $total entries; $valid valid; $expired expired"
+}
+
+# Warm cache (common queries)
+cache_warm() {
+    echo_info "warming cache..."
+
+    # Check whether a SCIP index exists
+    if [ ! -f "index.scip" ]; then
+        echo_warn "SCIP index not found; cannot warm graph cache"
+        return 1
+    fi
+
+    # Cache common query results
+    # Note: actual MCP calls must be executed in Claude Code.
+    # Here we only clean expired cache and keep placeholders.
+
+    # Clean expired cache
+    for cache_file in "$CACHE_DIR"/*.json; do
+        if [ -f "$cache_file" ]; then
+            if ! is_cache_valid "$cache_file"; then
+                rm -f "$cache_file"
+                echo_info "removed expired: $(basename "$cache_file")"
+            fi
+        fi
+    done
+
+    echo_info "cache warm-up complete"
+    echo ""
+    echo "Tip: in Claude Code, run these commands to warm common queries:"
+    echo "  - mcp__ckb__getArchitecture(depth=2)"
+    echo "  - mcp__ckb__getHotspots(limit=20)"
+    echo "  - mcp__ckb__listKeyConcepts(limit=12)"
+}
+
+# Main
+case "$ACTION" in
+    get) cache_get ;;
+    set) cache_set ;;
+    clear) cache_clear ;;
+    status) cache_status ;;
+    warm) cache_warm ;;
+    *)
+        echo "error: specify an action: get, set, clear, status, warm"
+        echo "hint: use -h for help"
+        exit 1
+        ;;
+esac