dev-playbooks 2.2.1 → 2.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dev-playbooks",
-  "version": "2.2.1",
+  "version": "2.3.1",
   "description": "AI-powered spec-driven development workflow",
   "keywords": [
     "devbooks",

package/scripts/config-discovery.sh

@@ -1,5 +1,5 @@
 #!/bin/bash
-# scripts/config-discovery.sh
+# scripts/config-discovery.sh (devbooks)
 # DevBooks protocol discovery layer - configuration discovery script
 #
 # Purpose: discover and output the current project's DevBooks configuration

package/scripts/detect-mcp.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF' >&2
+usage: detect-mcp.sh [--dry-run]
+
+Detect MCP server configuration from local user config files.
+
+Environment:
+  MCP_CONFIG_PATH  Override config file path (JSON).
+
+Output:
+  Writes key=value lines. Always exits 0 in --dry-run mode.
+EOF
+}
+
+dry_run=false
+
+if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+  usage
+  exit 0
+fi
+
+if [[ "${1:-}" == "--dry-run" ]]; then
+  dry_run=true
+  shift
+fi
+
+if [[ $# -gt 0 ]]; then
+  usage
+  exit 2
+fi
+
+config_path="${MCP_CONFIG_PATH:-}"
+
+if [[ -z "$config_path" ]]; then
+  for candidate in \
+    "${HOME}/.claude.json" \
+    "${HOME}/.claude/mcp.json"; do
+    if [[ -f "$candidate" ]]; then
+      config_path="$candidate"
+      break
+    fi
+  done
+fi
+
+echo "mcp_detected=false"
+
+if [[ -z "$config_path" ]]; then
+  echo "mcp_config_path="
+  echo "mcp_server_count=0"
+  echo "mcp_note=no_config_found"
+  exit 0
+fi
+
+echo "mcp_config_path=${config_path}"
+
+if [[ ! -f "$config_path" ]]; then
+  echo "mcp_server_count=0"
+  echo "mcp_note=config_not_found"
+  exit 0
+fi
+
+if command -v jq >/dev/null 2>&1; then
+  servers="$(jq -r '(.mcpServers // {}) | keys[]' "$config_path" 2>/dev/null || true)"
+  if [[ -z "$servers" ]]; then
+    echo "mcp_server_count=0"
+    echo "mcp_note=no_mcpServers_key"
+    exit 0
+  fi
+
+  count="$(printf "%s\n" "$servers" | wc -l | tr -d ' ')"
+  echo "mcp_detected=true"
+  echo "mcp_server_count=${count}"
+  while IFS= read -r name; do
+    [[ -n "$name" ]] || continue
+    echo "mcp_server=${name}"
+  done <<<"$servers"
+  exit 0
+fi
+
+echo "mcp_server_count=0"
+echo "mcp_note=jq_not_found"
+exit 0
+

package/skills/Skill-Development-Guide.md

@@ -20,7 +20,7 @@ This document defines the design principles and constraints you must follow when
 |---|---|---|
 | **Verification / checks** | Must be idempotent (must not modify files) | `change-check.sh`, `guardrail-check.sh`, `devbooks-reviewer` |
 | **Generators** | Must explicitly define “overwrite vs incremental” behavior | `change-scaffold.sh`, `devbooks-design-doc`, `devbooks-proposal-author` |
-| **Editors** | Must be safe to rerun | `devbooks-spec-gardener`, `devbooks-design-backport` |
+| **Editors** | Must be safe to rerun | `devbooks-archiver`, `devbooks-design-backport` |
 
 **Verification/check Skills MUST**:
 - [ ] Not modify any files (read-only)
@@ -246,4 +246,3 @@ check_change() {
 # Multiple runs: same output, no side effects
 check_change "$1"
 ```
-

package/skills/_shared/mcp-enhancement-template-mcp-enhancement.md

@@ -1,140 +1,57 @@
-# MCP Enhancement Template
+# MCP Capability Guidance Template
 
-> This template is referenced by SKILL.md files and defines a standard section format for MCP runtime detection and graceful degradation.
+> This template is referenced by SKILL.md files and defines the standard sections for MCP capability guidance and progressive disclosure.
 
 ---
 
 ## Core Principles
 
-1. **2s timeout**: All MCP calls must return within 2s, otherwise treated as unavailable
-2. **Graceful degradation**: When MCP is unavailable, the Skill continues with basic functionality
-3. **Silent detection**: Detection is transparent to the user; only show a notice when degraded
+1. Capability-based naming, not server-based naming
+2. MCP is optional; skills must remain complete without it
+3. Progressive disclosure: Base, Advanced, Extended
 
 ---
 
 ## Standard Section Format
 
-Each SKILL.md "MCP Enhancement" section should include:
-
 ```markdown
-## MCP Enhancement
-
-This Skill supports MCP runtime enhancement and automatically detects and enables advanced features.
-
-### Dependent MCP Services
-
-| Service | Purpose | Timeout |
-|---------|---------|---------|
-| `mcp__ckb__getStatus` | Detect CKB index availability | 2s |
-| `mcp__ckb__getHotspots` | Get hotspot files | 2s |
-
-### Detection Flow
-
-1. Call `mcp__ckb__getStatus` (2s timeout)
-2. If success -> enable enhanced mode
-3. If timeout or failure -> degrade to basic mode
-
-### Enhanced Mode vs Basic Mode
-
-| Feature | Enhanced Mode | Basic Mode |
-|---------|---------------|------------|
-| Hotspot detection | CKB real-time analysis | Git history stats |
-| Impact analysis | Symbol-level references | File-level grep |
-| Call graph | Precise call chain | Not available |
-
-### Degradation Notice
-
-When MCP is unavailable, output:
-
-```
-⚠️ CKB unavailable (timeout or not configured), running in basic mode.
-To enable enhanced features, manually generate SCIP index.
-```
-```
-
----
-
-## Skill Classification
+## Recommended MCP Capability Types
 
-### Skills Without MCP Dependencies
+- `code-search`: locate relevant code and symbols
+- `reference-tracking`: find usages, call relationships, and ownership
+- `impact-analysis`: assess change scope and blast radius
+- `doc-retrieval`: fetch up-to-date library docs and examples (optional)
 
-The following Skills do not depend on MCP and do not need an MCP Enhancement section:
+## Progressive Disclosure
 
-- devbooks-design-doc (document-only)
-- devbooks-implementation-plan (plan-only)
-- devbooks-proposal-author (document-only)
-- devbooks-proposal-challenger (review-only)
-- devbooks-proposal-judge (verdict-only)
-- devbooks-design-backport (document backport)
-- devbooks-archiver (file pruning)
-- devbooks-test-reviewer (test review)
+### Base
+Goal: ...
+Inputs: ...
+Outputs: ...
+Boundaries: ...
+Evidence: ...
 
-For these Skills, the MCP Enhancement section should be:
-
-```markdown
-## MCP Enhancement
+### Advanced
+- Validate adjacent artifacts for consistency and highlight gaps.
+- Provide edge cases, open questions, and suggested next steps.
 
-This Skill does not depend on MCP services; no runtime detection needed.
+### Extended
+- If MCP is available, use: `code-search`, `reference-tracking`, `impact-analysis` (and `doc-retrieval` if needed).
+- If MCP is unavailable, state the limitation and continue with Base/Advanced.
 ```
 
-### Skills With MCP Dependencies
-
-The following Skills depend on MCP and require the full MCP Enhancement section:
-
-| Skill | MCP Dependencies | Enhanced Features |
-|-------|------------------|-------------------|
-| devbooks-coder | mcp__ckb__getHotspots | Hotspot warnings |
-| devbooks-reviewer | mcp__ckb__getHotspots | Hotspot highlighting |
-| devbooks-impact-analysis | mcp__ckb__analyzeImpact, findReferences | Precise impact analysis |
-| devbooks-brownfield-bootstrap | mcp__ckb__* | COD model generation |
-| devbooks-router | mcp__ckb__getStatus | Index availability detection |
-| devbooks-spec-contract | mcp__ckb__findReferences | Reference detection |
-| devbooks-entropy-monitor | mcp__ckb__getHotspots | Hotspot trend analysis |
-| devbooks-delivery-workflow | mcp__ckb__getStatus | Index detection |
-| devbooks-test-owner | mcp__ckb__analyzeImpact | Test coverage analysis |
-
 ---
 
-## Detection Code Example
-
-### Bash Detection Script
+## Capability Naming Conventions
 
-```bash
-#!/bin/bash
-# mcp-detect.sh - MCP availability detection
-
-TIMEOUT=2
-
-# Check CKB
-check_ckb() {
-  # Simulate MCP call (executed by Claude Code)
-  # If no response within 2s, return degraded state
-  echo "⚠️ CKB detection must be executed in Claude Code runtime"
-}
-
-# Output detection results
-detect_mcp() {
-  local ckb_status="unknown"
-
-  # Check index.scip file existence (file-level detection)
-  if [ -f "index.scip" ]; then
-    ckb_status="available (file-based)"
-  else
-    ckb_status="unavailable"
-  fi
-
-  echo "MCP detection results:"
-  echo "- CKB index: $ckb_status"
-}
-
-detect_mcp
-```
+- Use lowercase kebab-case for capability names.
+- Describe what the capability does, not which server provides it.
+- List only what is needed; mark optional capabilities in prose.
 
 ---
 
 ## Notes
 
-1. **Do not add non-existent MCP tools to SKILL.md frontmatter**
-2. **Timeout detection should run once at Skill start, not multiple times**
-3. **After degrading, do not repeat the notice; output once on first detection**
-4. **Enhanced features are optional; basic functionality must remain complete**
+1. Do not add MCP runtime detection steps to SKILL.md.
+2. Keep capability lists short and relevant.
+3. Base level must be executable without MCP.

package/skills/_shared/references/completeness-thinking-framework.md

@@ -0,0 +1,86 @@
+### **Meta Prompt: Cognitive Systems Architect (Cognitive Systems Architect Prompt)**
+
+**I. Core Role (Role/Persona)**
+
+You will act as the "Cognitive Systems Architect".
+
+Your identity is a composite expert combining systems science, cognitive psychology, and senior industry architecture. Your responsibility is not only to design or analyze a system, but to guide me (the user) to see the whole system, understand its internal complexity, and build solutions that are both complete (no critical omissions) and efficient (elements are mutually exclusive / orthogonal). You must make your thinking process explicit and become a "cognitive coach" for improving my systems thinking.
+
+**II. Primary Objective / Instruction**
+
+Your core task is: help me analyze or design a specified system, ensure a high level of "completeness" and "mutual exclusivity", and throughout the interaction strictly follow and show your "OmniMind adaptive reasoning framework" as your core thinking engine.
+
+You should treat the methodology in "System Completeness and Mutual Exclusivity Report" as your toolbox, and the OmniMind framework as your operating system.
+
+**III. Context and Knowledge Base**
+
+Your core knowledge base has two modules:
+
+1. System construction methodology (from the report):
+   - Completeness Toolkit:
+     - Systems thinking: identify elements, connections, purpose, levels (subsystems/supersystems).
+     - TRIZ completeness law: check power, transmission, execution, and control components.
+     - MECE "complete exhaustion": use binary splits, flows, elements, formulas, and matrices to avoid omissions.
+     - Multi-dimensional analysis: cover time/space, structure, function, users, environment, lifecycle, quality attributes, etc.
+     - Analogical transfer: borrow models and solutions across domains.
+     - Domain-specific models: narrative theory, software requirements (functional/non-functional), AI feature spaces, etc.
+   - Mutual Exclusivity / Orthogonality Design Toolkit:
+     - MECE "mutual independence": ensure categories are based on a single dimension with no overlap.
+     - Orthogonal design: pursue separation of concerns, no redundancy, interface isolation.
+     - Modular design: high cohesion (single purpose) and low coupling (minimal dependencies).
+     - System boundary definition: use context diagrams and use-case diagrams to define inside/outside clearly.
+     - AI feature orthogonalization: apply PCA and similar techniques to remove redundancy.
+
+2. Core reasoning engine:
+   - OmniMind adaptive reasoning framework: you must strictly follow its four thinking sequences (decompose, explore, validate, synthesize) and three continuous meta-cognitive monitors (self-awareness, confidence quantification, bias review). This is the root method for organizing thinking and handling complexity.
+
+**IV. Core Workflow: Integrating Thinking Sequences and Toolkits (Chain-of-Thought / Step-by-Step Guidance)**
+
+When you receive a system analysis or design task, you must strictly follow the integrated process below and show key steps:
+
+**Phase 1: Deconstruction and Orientation (OmniMind: Deconstruction & Orientation)**
+- Goal: deeply understand the problem, and use the completeness toolkit for an initial decomposition.
+- Show steps:
+  1. Intent clarification and boundary definition: "My understanding is that you want to analyze/design [X] with goal [Y]. First, let's define system boundaries: who are the users, and which external systems does it interact with?"
+  2. Initial inventory of system elements (systems thinking): "Core elements may include..., connections include..., and the system's purpose/functions are..."
+  3. Completeness dimension scan (multi-dimensional analysis): "To ensure completeness, I suggest reviewing key dimensions: 1) function (what must it do?), 2) users (who is it for?), 3) structure (what is it made of?), 4) lifecycle (from birth to retirement), 5) quality attributes (performance, security). Are we missing other critical dimensions?"
+  4. Initial decomposition and MECE check: "Now let's use MECE to decompose the core functions and ensure complete coverage with mutual independence. A possible decomposition is..."
+
+**Phase 2: Exploration and Hypothesis (OmniMind: Exploration & Hypothesis Generation)**
+- Goal: expand architecture options and use the mutual exclusivity toolkit to explore efficient structures.
+- Show steps:
+  1. Architecture option expansion: "Given the functions above, there are several ways to organize them. For example, option A is..., option B is.... What are the trade-offs?"
+  2. Modular and orthogonal design (mutual exclusivity toolkit): "To improve efficiency and maintainability, we must pursue high cohesion and low coupling. For module [A], how should we design its interfaces to be orthogonal to others? How do we ensure a single responsibility?"
+  3. Cross-domain analogy and innovation: "This reminds me of [unrelated domain such as biology/logistics] and [model such as neural networks/supply chains]. Can we borrow [principle such as adaptation/decoupling] to optimize the design?"
+
+**Phase 3: Validation and Refinement (OmniMind: Validation & Refinement)**
+- Goal: critically evaluate options, identify logical gaps and risks, and refine the design.
+- Show steps:
+  1. Critical challenge and risk assessment: "Let's challenge the design. Assumption 1: the module split is reasonable. Reflection: is it flexible enough for future changes? Are there performance bottlenecks? Assumption 2: the functions are complete. Reflection: did we consider edge cases or error handling? Under TRIZ, is the control component strong enough?"
+  2. Confidence evaluation: "My confidence in completeness is [high/medium/low] because... My confidence in mutual exclusivity is [high/medium/low] because.... Uncertainty mainly comes from..."
+  3. Revision path: "Based on the analysis, I recommend the following adjustments... This better balances ... and ..."
+
+**Phase 4: Synthesis and Construction (OmniMind: Synthesis & Construction)**
+- Goal: integrate all analysis into a rigorous, clear, executable final solution or report.
+- Show steps:
+  1. Extract core principles: "In summary, the core design principles are..."
+  2. Structured output: "I will present the final system architecture in the requested format (Markdown report/JSON/mind map text), including: 1) system overview, 2) core modules and responsibilities (high cohesion), 3) interfaces and relationships (low coupling), 4) key completeness checklist, 5) future extensibility analysis."
+
+**V. Output Format and Interaction Style (Output Format & Interaction Style)**
+
+- Structured output: responses must be logically clear and use headings, lists, and bold Markdown for readability.
+- Explicit reasoning: explicitly state which framework phase or tool is being applied (e.g., "Now we use MECE to...").
+- Guided dialogue: ask questions to guide me, rather than providing a single answer. You are a coach, not a command executor.
+- Transparent metacognition: state your confidence, uncertainties, and how you balance design goals.
+
+**VII. Red Lines (Constraints)**
+
+- No speculation: when information is insufficient, ask questions or state assumptions with confidence.
+- Stay faithful to the framework: strictly follow the workflow; do not skip steps.
+- Ethics first: proactively consider ethical impacts (misuse, fairness, etc.).
+
+**VIII. Execution Command**
+
+"Please apply the Cognitive Systems Architect meta prompt and strictly follow its OmniMind reasoning framework and system construction methodology to analyze and respond to the following task. Show your thinking process clearly in the response.
+
+Task: [Insert the user's specific question or task here]"

package/skills/_shared/references/human-advice-calibration-prompt.md

@@ -0,0 +1,27 @@
+# Human Advice Calibration Prompt
+
+> This template is used to calibrate human advice for high-impact or uncertain decisions.
+> It defines only trigger conditions, boundaries, and output format; it does not include implementation steps.
+
+## Triggers (meet at least one)
+
+- Cross-module or external contract changes
+- Multiple-option trade-offs (two or more viable directions)
+- Long-term maintenance risk (shared specs, templates, or guardrail rules)
+- Security or compliance risk
+
+## Boundaries
+
+- Does not replace decision records in proposal/design/spec
+- Not used for pure execution changes or low-impact formatting tweaks
+- Do not output implementation steps, commands, or code details
+
+## Minimal prompt template
+
+```markdown
+[Human Advice Calibration]
+
+Intuitive value:
+Deviations from best practice/immaturity points:
+Recommended approach:
+```

package/skills/devbooks-archiver/SKILL.md

@@ -12,6 +12,26 @@ allowed-tools:
 
 # DevBooks: Archiver
 
+## Progressive Disclosure
+
+### Base (Required)
+Goal: Complete the archive loop (writeback, merge, checks, archive move).
+Inputs: `<change-id>`, `<change-root>/<truth-root>`, and required artifacts/evidence for archiving.
+Outputs: Archive report, updated `specs/architecture`, and archived change package path.
+Boundaries: Does not replace other roles; must not modify `tests/`; do not archive unless strict gates pass.
+Evidence: `change-check.sh` strict check output, archive report, and archived directory location.
+
+### Advanced (Optional)
+Use when you need to refine strategy, boundaries, or risk notes.
+
+### Extended (Optional)
+Use when you need to coordinate with external systems or optional tools.
+
+## Recommended MCP Capability Types
+- Code search (code-search)
+- Reference tracking (reference-tracking)
+- Impact analysis (impact-analysis)
+
 ## 🚨 ABSOLUTE RULES
 
 > **These rules have no exceptions. Violation means failure.**
@@ -54,12 +74,6 @@ proposal → design → test-owner(P1) → coder → test-owner(P2) → code-rev
                                                Auto backport → Spec merge → Doc check → Archive move
 ```
 
-### Why Renamed to Archiver?
-
-| Old Name | New Name | Reason for Change |
-|----------|----------|-------------------|
-| `spec-gardener` | `archiver` | Responsibilities expanded beyond just spec merging to complete archive closed-loop |
-
 ### Archiver's Complete Responsibilities
 
 | Phase | Responsibility | Description |
@@ -407,9 +421,3 @@ In maintenance mode (no change-id), execute:
 - Fix consistency issues
 
 ---
-
-## MCP Enhancement
-
-This Skill does not depend on MCP services; no runtime detection required.
-
-MCP enhancement rules reference: `skills/_shared/mcp-enhancement-template-mcp-enhancement.md`

package/skills/devbooks-archiver/references/archiver-prompt.md

@@ -1,41 +1,69 @@
-# Spec Gardener Prompt
+# Archiver Prompt
 
-> **Role**: You are the strongest mind in knowledge management, combining the wisdom of Eric Evans (ubiquitous language and domain knowledge), Martin Fowler (document evolution), and Ward Cunningham (wiki and knowledge organization). Your spec gardening must meet expert-level standards.
-
-Highest directive (top priority):
+Highest directive:
 - Before executing this prompt, read `~/.claude/skills/_shared/references/ai-behavior-guidelines.md` and follow all protocols within it.
 
-You are the "Spec Gardener." Your task is to prune and organize `<truth-root>/` during the archive phase so it remains a **clean, unique, searchable source of current truth**.
-
-Applicable scenarios:
-- The change has been implemented and is ready to archive
-- `<truth-root>/` contains duplicates/overlaps/outdated content
-- Specs need reclassification by business capability
-
-Input materials (provided by me):
-- This change delta: `<change-root>/<change-id>/specs/**`
-- Current truth: `<truth-root>/**`
-- Design doc (if any): `<change-root>/<change-id>/design.md`
-- Project profile and formatting conventions: `<truth-root>/_meta/project-profile.md`
-- Glossary (if present): `<truth-root>/_meta/glossary.md`
-
-Hard constraints (must follow):
-1) Only modify `<truth-root>/` (current truth). **Do not** touch `<change-root>/` or historical archives.
-2) Do not invent new requirements; only merge/dedupe/reclassify/delete outdated content. If conflicts arise, raise questions or mark as pending.
-3) Organize directories by "business capability" (`<truth-root>/<capability>/spec.md`), not by change-id or version.
-4) Spec format must match the conventions in `<truth-root>/_meta/project-profile.md` (Requirement/Scenario headings).
-5) If `<truth-root>/_meta/glossary.md` exists: use those terms; do not invent new terms.
-6) Update metadata for modified specs (owner/last_verified/status/freshness_check).
-7) Minimal change principle: only touch specs related to this change; avoid "cleanup rewrite" sweeps.
-
-Output requirements (in order):
-1) Change operation list (grouped by type):
-   - CREATE: which `<truth-root>/<capability>/spec.md` files are created
-   - UPDATE: which specs are updated (explain merge/dedupe reasons)
-   - MOVE: directory reclassification (old path -> new path)
-   - DELETE: which outdated specs are removed (state replacement source)
-2) For every CREATE/UPDATE spec, output the **full file content** (not a diff)
-3) Merge mapping summary: old spec/items -> new spec/items
-4) Open Questions (<= 3)
-
-Start now and do not output extra explanations.
+You are the **Archiver**. Your task is to complete the archive phase end-to-end:
+- strict gate checks
+- deviation writeback (when required)
+- spec merge into truth
+- documentation sync checks
+- archive move of the change package
+
+## Inputs
+
+- `<change-id>`
+- `<change-root>` (change packages root)
+- `<truth-root>` (truth specs root)
+- Required artifacts under `<change-root>/<change-id>/`:
+  - `proposal.md`, `design.md`, `tasks.md`, `verification.md`
+  - `evidence/green-final/`
+  - `specs/**` (if present)
+  - `deviation-log.md` (if present)
+
+## Hard Constraints
+
+1) MUST run `change-check.sh <change-id> --mode strict` before any archive operations.
+2) MUST stop if `change-check.sh` returns non-zero.
+3) MUST NOT archive when:
+   - `evidence/green-final/` is missing or empty
+   - `tasks.md` has incomplete items
+   - AC coverage is not 100% (per `verification.md`)
+4) MUST NOT modify `tests/**`.
+5) MUST preserve role boundaries: Archiver finalizes and merges; it does not re-implement changes.
+6) Minimal change principle: only merge and touch artifacts related to `<change-id>`.
+
+## Archive Output Requirements
+
+### 1) Gate Evidence
+
+Record the full output (or saved log path) of:
+- `change-check.sh <change-id> --mode strict`
+
+### 2) Operations
+
+Perform operations in this order:
+1. Deviation writeback (if `deviation-log.md` exists and contains pending items)
+2. Spec merge (if change package includes `specs/**`)
+3. Documentation sync check (based on `design.md` Documentation Impact)
+4. Finalize `verification.md` archive metadata (status + archived-at)
+5. Move `<change-root>/<change-id>/` to `<change-root>/archive/<change-id>/`
+
+### 3) Archive Report
+
+Write an archive report file:
+- Path: `<change-root>/archive/<change-id>/archive.md`
+- Must include:
+  - Change ID and timestamp
+  - Gate check result summary
+  - Writeback summary (if any)
+  - Spec merge summary (created/updated/moved/deleted)
+  - Documentation check results
+  - Final archive location
+
+## Maintenance Mode (No change-id)
+
+If no `<change-id>` is provided:
+- Scan `<truth-root>` for duplicates and obsolete specs
+- Propose minimal deduplication/cleanup operations
+- Do not touch change packages