dev-playbooks 1.0.0

package/skills/devbooks-delivery-workflow/scripts/verify-npm-package.sh

@@ -0,0 +1,123 @@
+#!/bin/bash
+# verify-npm-package.sh - Verify npm package structure
+#
+# Verify AC-011 ~ AC-016
+
+set -uo pipefail  # Remove -e, handle errors manually
+
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+NC='\033[0m'
+
+PASSED=0
+FAILED=0
+
+check() {
+    local name="$1"
+    local result="$2"
+    if [[ "$result" == "0" ]]; then
+        echo -e "${GREEN}✅ $name${NC}"
+        PASSED=$((PASSED + 1))
+    else
+        echo -e "${RED}❌ $name${NC}"
+        FAILED=$((FAILED + 1))
+    fi
+}
+
+echo "=== npm Package Verification ==="
+echo ""
+
+# Use an isolated npm cache to avoid permission issues in CI/dev environments.
+NPM_CACHE_DIR="$(mktemp -d 2>/dev/null || mktemp -d -t 'devbooks-npm-cache')"
+cleanup() {
+    rm -rf "$NPM_CACHE_DIR"
+}
+trap cleanup EXIT
+
+# AC-011: CLI entry exists and is executable
+# Note: Design changed to `devbooks init` instead of `create-devbooks`
+echo "AC-011: Checking CLI entry..."
+if [[ -f "bin/devbooks.js" ]] && [[ -x "bin/devbooks.js" ]]; then
+    check "AC-011: CLI entry exists and is executable" "0"
+else
+    check "AC-011: CLI entry exists and is executable" "1"
+fi
+
+# AC-012: package.json exists and is valid
+echo "AC-012: Checking package.json..."
+if [[ -f "package.json" ]] && node -e '
+  const fs = require("fs");
+  const pkg = JSON.parse(fs.readFileSync("package.json", "utf8"));
+  const hasName = typeof pkg.name === "string" && pkg.name.trim().length > 0;
+  const bin = pkg.bin;
+  const normalize = (p) => (typeof p === "string" && p.startsWith("./")) ? p.slice(2) : p;
+  const hasBin = (() => {
+    if (typeof bin === "string") return normalize(bin) === "bin/devbooks.js";
+    if (!bin || typeof bin !== "object") return false;
+    return Object.values(bin).some(v => typeof v === "string" && normalize(v) === "bin/devbooks.js");
+  })();
+  process.exit(hasName && hasBin ? 0 : 1);
+' >/dev/null 2>&1; then
+    check "AC-012: package.json exists and is valid" "0"
+else
+    check "AC-012: package.json exists and is valid" "1"
+fi
+
+# AC-013: templates/ directory exists
+echo "AC-013: Checking templates/ directory..."
+if [[ -d "templates" ]]; then
+    check "AC-013: templates/ directory exists" "0"
+else
+    check "AC-013: templates/ directory exists" "1"
+fi
+
+# AC-014: Skills count is correct (21 devbooks-* Skills)
+echo "AC-014: Checking Skills count..."
+skill_count=$(ls -d skills/devbooks-* 2>/dev/null | wc -l | tr -d ' ')
+if [[ "$skill_count" -ge 20 ]]; then
+    check "AC-014: Skills count is correct ($skill_count)" "0"
+else
+    check "AC-014: Skills count is correct ($skill_count, expected >= 20)" "1"
+fi
+
+# AC-015: Packaging is controlled (files whitelist or .npmignore)
+echo "AC-015: Checking packaging control..."
+has_files_whitelist="1"
+if [[ -f "package.json" ]] && node -e '
+  const fs = require("fs");
+  const pkg = JSON.parse(fs.readFileSync("package.json", "utf8"));
+  const files = pkg.files;
+  const ok = Array.isArray(files) && files.length > 0;
+  process.exit(ok ? 0 : 1);
+' >/dev/null 2>&1; then
+    has_files_whitelist="0"
+fi
+if [[ "$has_files_whitelist" == "0" || -f ".npmignore" ]]; then
+    check "AC-015: packaging is controlled" "0"
+else
+    check "AC-015: packaging is controlled" "1"
+fi
+
+# AC-016: npm pack does not include project change packages (exclude template directory)
+# Note: templates/dev-playbooks/changes/ is user project template, should be included
+#       dev-playbooks/changes/ is project development change package, should be excluded
+echo "AC-016: Checking npm pack output..."
+pack_output="$(npm --cache "$NPM_CACHE_DIR" pack --dry-run --ignore-scripts 2>&1 || true)"
+if echo "$pack_output" | grep "changes/" | grep -v "templates/" | grep -q "changes/"; then
+    check "AC-016: npm pack does not include changes/" "1"
+else
+    check "AC-016: npm pack does not include changes/" "0"
+fi
+
+echo ""
+echo "=== Results ==="
+echo "Passed: $PASSED"
+echo "Failed: $FAILED"
+
+if [[ $FAILED -eq 0 ]]; then
+    echo -e "${GREEN}All passed!${NC}"
+    exit 0
+else
+    echo -e "${RED}Some checks failed${NC}"
+    exit 1
+fi

package/skills/devbooks-delivery-workflow/scripts/verify-openspec-free.sh

@@ -0,0 +1,81 @@
+#!/bin/bash
+# verify-openspec-free.sh - Verify OpenSpec references are removed
+#
+# Verifies AC-001 ~ AC-004
+
+set -uo pipefail  # omit -e; handle errors manually
+
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+NC='\033[0m'
+
+PASSED=0
+FAILED=0
+
+check() {
+    local name="$1"
+    local result="$2"
+    if [[ "$result" == "0" ]]; then
+        echo -e "${GREEN}✅ $name${NC}"
+        PASSED=$((PASSED + 1))
+    else
+        echo -e "${RED}❌ $name${NC}"
+        FAILED=$((FAILED + 1))
+    fi
+}
+
+echo "=== OpenSpec removal verification ==="
+echo ""
+
+# AC-001: No OpenSpec references (exclude legitimate references)
+echo "AC-001: Checking OpenSpec references..."
+# Exclude legitimate references:
+# - backup, changes, .git: history / work dirs
+# - migrate-from-openspec.sh: migration script
+# - verify-*.sh: verification scripts
+# - c4.md: architecture doc (records historical changes)
+# - specs/config-protocol/spec.md: rules definition doc
+# - specs/slash-commands/spec.md: historical record doc
+ref_count=$(grep -rn "openspec\|OpenSpec" . --include="*.md" --include="*.sh" --include="*.yaml" --include="*.yml" --include="*.js" 2>/dev/null | grep -v backup | grep -v changes | grep -v "\.git" | grep -v "DEVBOOKS-EVOLUTION-PROPOSAL.md" | grep -v "migrate-from-openspec.sh" | grep -v "tests/" | grep -v "verify-openspec-free.sh" | grep -v "verify-all.sh" | grep -v "c4.md" | grep -v "specs/config-protocol/spec.md" | grep -v "specs/slash-commands/spec.md" | wc -l | tr -d ' ') || ref_count=0
+if [[ "$ref_count" == "0" ]]; then
+    check "AC-001: OpenSpec references = 0" "0"
+else
+    check "AC-001: OpenSpec references = 0 (remaining: $ref_count)" "1"
+fi
+
+# AC-002: setup/openspec removed
+echo "AC-002: Checking setup/openspec directory..."
+if [[ ! -d "setup/openspec" ]]; then
+    check "AC-002: setup/openspec removed" "0"
+else
+    check "AC-002: setup/openspec removed" "1"
+fi
+
+# AC-003: .claude/commands/openspec removed
+echo "AC-003: Checking .claude/commands/openspec directory..."
+if [[ ! -d ".claude/commands/openspec" ]]; then
+    check "AC-003: .claude/commands/openspec removed" "0"
+else
+    check "AC-003: .claude/commands/openspec removed" "1"
+fi
+
+# AC-004: dev-playbooks/specs/openspec-integration removed
+echo "AC-004: Checking dev-playbooks/specs/openspec-integration directory..."
+if [[ ! -d "dev-playbooks/specs/openspec-integration" ]]; then
+    check "AC-004: dev-playbooks/specs/openspec-integration removed" "0"
+else
+    check "AC-004: dev-playbooks/specs/openspec-integration removed" "1"
+fi
+
+echo ""
+echo "=== Summary ==="
+echo "passed: $PASSED"
+echo "failed: $FAILED"
+
+if [[ $FAILED -eq 0 ]]; then
+    echo -e "${GREEN}All checks passed!${NC}"
+    exit 0
+else
+    echo -e "${RED}Some checks failed${NC}"
+    exit 1
+fi

package/skills/devbooks-delivery-workflow/scripts/verify-slash-commands.sh

@@ -0,0 +1,146 @@
+#!/bin/bash
+# verify-slash-commands.sh - Verify slash command definitions
+#
+# Verifies AC-001 (24 commands) and AC-002 (1:1 command ↔ skill mapping)
+
+set -uo pipefail
+
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+PASSED=0
+FAILED=0
+
+check() {
+    local name="$1"
+    local result="$2"
+    if [[ "$result" == "0" ]]; then
+        echo -e "${GREEN}✅ $name${NC}"
+        PASSED=$((PASSED + 1))
+    else
+        echo -e "${RED}❌ $name${NC}"
+        FAILED=$((FAILED + 1))
+    fi
+}
+
+check_skill_mapping() {
+    local cmd="$1"
+    local expected_skill="$2"
+    local file="$COMMANDS_DIR/$cmd.md"
+    if [[ -f "$file" ]]; then
+        if grep -q "skill: $expected_skill" "$file"; then
+            check "AC-002: $cmd.md → $expected_skill" "0"
+        else
+            check "AC-002: $cmd.md → $expected_skill (skill metadata mismatch)" "1"
+        fi
+    fi
+}
+
+echo "=== Slash command verification (21 core + 3 backward-compatible = 24 total) ==="
+echo ""
+
+COMMANDS_DIR="templates/claude-commands/devbooks"
+
+# AC-001: Check command count (24 = 21 core + 3 backward-compatible)
+echo "AC-001: Checking command count..."
+cmd_count=$(ls "$COMMANDS_DIR"/*.md 2>/dev/null | wc -l | tr -d ' ')
+if [[ "$cmd_count" -eq 24 ]]; then
+    check "AC-001: Command count is 24 (21 core + 3 backward-compatible)" "0"
+else
+    check "AC-001: Command count is 24 (actual: $cmd_count)" "1"
+fi
+
+echo ""
+echo "=== Checking presence of the 21 core command files ==="
+
+# List of 21 core command files
+COMMANDS=(
+    "router"
+    "proposal"
+    "challenger"
+    "judge"
+    "debate"
+    "design"
+    "backport"
+    "plan"
+    "spec"
+    "gardener"
+    "test"
+    "test-review"
+    "code"
+    "review"
+    "delivery"
+    "c4"
+    "impact"
+    "entropy"
+    "federation"
+    "bootstrap"
+    "index"
+)
+
+for cmd in "${COMMANDS[@]}"; do
+    if [[ -f "$COMMANDS_DIR/$cmd.md" ]]; then
+        check "AC-011~AC-031: $cmd.md exists" "0"
+    else
+        check "AC-011~AC-031: $cmd.md exists" "1"
+    fi
+done
+
+echo ""
+echo "=== AC-002: Checking command ↔ skill mapping ==="
+
+# Command -> Skill mapping checks
+check_skill_mapping "router" "devbooks-router"
+check_skill_mapping "proposal" "devbooks-proposal-author"
+check_skill_mapping "challenger" "devbooks-proposal-challenger"
+check_skill_mapping "judge" "devbooks-proposal-judge"
+check_skill_mapping "debate" "devbooks-proposal-debate-workflow"
+check_skill_mapping "design" "devbooks-design-doc"
+check_skill_mapping "backport" "devbooks-design-backport"
+check_skill_mapping "plan" "devbooks-implementation-plan"
+check_skill_mapping "spec" "devbooks-spec-contract"
+check_skill_mapping "gardener" "devbooks-spec-gardener"
+check_skill_mapping "test" "devbooks-test-owner"
+check_skill_mapping "test-review" "devbooks-test-reviewer"
+check_skill_mapping "code" "devbooks-coder"
+check_skill_mapping "review" "devbooks-code-review"
+check_skill_mapping "delivery" "devbooks-delivery-workflow"
+check_skill_mapping "c4" "devbooks-c4-map"
+check_skill_mapping "impact" "devbooks-impact-analysis"
+check_skill_mapping "entropy" "devbooks-entropy-monitor"
+check_skill_mapping "federation" "devbooks-federation"
+check_skill_mapping "bootstrap" "devbooks-brownfield-bootstrap"
+check_skill_mapping "index" "devbooks-index-bootstrap"
+
+echo ""
+echo "=== AC-008: Checking backward-compatible commands ==="
+
+# Backward-compatible command list
+COMPAT_COMMANDS=("apply" "archive" "quick")
+
+for cmd in "${COMPAT_COMMANDS[@]}"; do
+    if [[ -f "$COMMANDS_DIR/$cmd.md" ]]; then
+        if grep -q "backward-compat: true" "$COMMANDS_DIR/$cmd.md"; then
+            check "AC-008: $cmd.md exists and is marked backward-compatible" "0"
+        else
+            check "AC-008: $cmd.md exists but missing backward-compat marker" "1"
+        fi
+    else
+        check "AC-008: $cmd.md exists" "1"
+    fi
+done
+
+echo ""
+echo "=== Summary ==="
+echo "passed: $PASSED"
+echo "failed: $FAILED"
+
+if [[ $FAILED -eq 0 ]]; then
+    echo -e "${GREEN}All checks passed!${NC}"
+    exit 0
+else
+    echo -e "${RED}Some checks failed${NC}"
+    exit 1
+fi

package/skills/devbooks-delivery-workflow/templates/handoff.md

@@ -0,0 +1,50 @@
+# Role Handoff Record
+
+## Handoff Metadata
+
+- **Change ID**: <change-id>
+- **Handoff from role**: <Test Owner / Design Owner / Planner / ...>
+- **Handoff to role**: <Coder / Reviewer / ...>
+- **Handoff time**: <YYYY-MM-DD HH:MM>
+- **Conversation/instance ID**: <session-id>
+
+## Handoff Content
+
+### Completed Deliverables
+
+- [ ] `design.md` - Design doc produced and reviewed
+- [ ] `tasks.md` - Implementation plan produced
+- [ ] `verification.md` - Acceptance tests defined
+- [ ] `tests/**` - Test code implemented
+- [ ] Red baseline recorded in `evidence/red-baseline/`
+
+### Context Information
+
+> Fill in key information the receiving role needs.
+
+- **Current status**: <brief progress summary>
+- **Key decisions**: <important decisions to know>
+- **Known issues**: <risks or issues likely to be encountered>
+- **References**: <other documents to read>
+
+### Remaining Work
+
+> List work the receiving role needs to complete.
+
+1. <remaining item 1>
+2. <remaining item 2>
+
+## Confirmation Signatures
+
+> After handoff, both sides confirm here.
+
+- [ ] **From-side confirmation**: I confirm the deliverables above are complete and the information is accurate.
+- [ ] **To-side confirmation**: I confirm I have received the handoff content and understand current status and remaining work.
+
+---
+
+## Notes
+
+> Optional: additional information to record.
+
+<fill in additional notes or leave blank>

package/skills/devbooks-design-backport/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: devbooks-design-backport
+description: devbooks-design-backport: Backport newly discovered constraints, conflicts, or gaps from implementation back to design.md (keeping design as the golden truth), with annotated decisions and impacts. Use when the user says "backport design/update design doc/Design Backport/design-implementation mismatch/need to clarify constraints" etc.
+tools:
+  - Glob
+  - Grep
+  - Read
+  - Write
+  - Edit
+---
+
+# DevBooks: Design Backport
+
+## Prerequisites: Configuration Discovery (Protocol-Agnostic)
+
+- `<truth-root>`: Current truth directory root
+- `<change-root>`: Change package directory root
+
+Before execution, you **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 the user**
+
+**Key Constraints**:
+- If `agents_doc` (rules document) is specified in configuration, **you must read that document first** before executing any operations
+- Do not guess directory roots
+- Do not skip reading the rules document
+
+## Execution Method
+
+1) First read and follow: `_shared/references/universal-gating-protocol.md` (verifiability + structural quality gating).
+2) Strictly execute according to the complete prompt: `references/design-backport-prompt.md`.
+
+---
+
+## Context Awareness
+
+This Skill automatically detects context before execution, identifying content that needs to be backported.
+
+Detection rules reference: `skills/_shared/context-detection-template.md`
+
+### Detection Flow
+
+1. Detect whether `design.md` exists
+2. Detect whether new discoveries (conflicts/constraints/gaps) were found during implementation
+3. Compare differences between design and implementation
+
+### Modes Supported by This Skill
+
+| Mode | Trigger Condition | Behavior |
+|------|-------------------|----------|
+| **Conflict Backport** | Design-implementation conflict detected | Record conflict points and resolutions |
+| **Constraint Backport** | New implementation constraints discovered | Add constraint conditions to design |
+| **Gap Backport** | Scenarios not covered by design detected | Add missing design decisions |
+
+### Detection Output Example
+
+```
+Detection Results:
+- design.md: Exists
+- Discoveries: 2 new constraints, 1 design conflict
+- Running Mode: Constraint Backport + Conflict Backport
+```
+
+---
+
+## MCP Enhancement
+
+This Skill does not depend on MCP services; no runtime detection required.
+
+MCP enhancement rules reference: `skills/_shared/mcp-enhancement-template.md`
+

package/skills/devbooks-design-backport/references/design-backport-prompt.md

@@ -0,0 +1,132 @@
+# Design Backport Prompt
+
+> **Role**: You are the strongest mind in design evolution, combining the wisdom of Michael Nygard (architecture decision records), Martin Fowler (evolutionary design), and Kent Beck (incremental improvement). Your design sync 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.
+
+# Prompt: Backport Design Docs When Implementation Plans Exceed Design Scope
+
+> Use case: You discover new constraints/concepts/acceptance criteria in the implementation plan (tasks/plan) that are not covered in the design docs (design/spec), causing drift between "plan-driven implementation" and "design-driven acceptance."
+
+Artifact locations (protocol agnostic):
+- Design doc usually at: `<change-root>/<change-id>/design.md`
+- Implementation plan usually at: `<change-root>/<change-id>/tasks.md`
+- Spec delta usually at: `<change-root>/<change-id>/specs/<capability>/spec.md`
+- Current truth at: `<truth-root>/` (do not backport by editing historical archives; update current truth with a new change package)
+
+> Goal: Backport content that *should be part of design* into the design doc to reduce divergence in testing, implementation, and acceptance.
+
+---
+
+## What Can Be Backported to the Design Doc
+
+Only backport plan items that meet at least one of the following (i.e., **Design-level**):
+
+1. **External semantics or user-visible behavior**
+
+- New/changed key user flows (explicit state machines, async sessions, cancellable/timeouts)
+- External contracts (API input/output shapes, error semantics, required fields, compatibility windows)
+
+2. **System-level invariants / red lines**
+
+- Cost/resource limits (e.g., prohibit N^2 LLM calls, hard caps like `max_llm_calls`, budget-triggered degradation)
+- Reliability/security red lines (e.g., multi-tenant isolation on by default, external untrusted boundaries, default isolation for injection)
+
+3. **Core data contracts and evolution strategy**
+
+- `schema_version`, required event envelope fields, idempotency key principles, compatibility strategy (DLQ/migration/replay)
+- Minimum standards for what must be replayable/auditable/traceable
+
+4. **Cross-cutting concerns**
+
+- Observability metrics, SLO/KPI, alerting and operational strategies
+- Lifecycle/retention policies (Valid/Quarantine/Garbage goals and rules)
+- Gradual rollout/rollback paths and feature flags
+
+5. **Key tradeoffs and decisions**
+
+- Why choose A over B, alternatives, risks, fallback strategies
+- New/changed Non-goals or Open Questions
+
+---
+
+## What Must NOT Be Backported
+
+The following are **Implementation-level** and should not be written into design docs (unless promoted to formal design decisions):
+
+- Specific file paths, class/function names, table/field names (unless they are stable architectural boundaries that must align)
+- PR splitting advice, task execution order, temporary scripts/commands
+- Over-detailed algorithm pseudocode (backport inputs/outputs/invariants/complexity limits/fallbacks instead of code)
+- One-off implementation conveniences without long-term value or verification
+
+---
+
+## Conflict Resolution (Plan vs Design)
+
+- **Design doc is the golden truth**: if plan conflicts with design, do not overwrite design with the plan.
+- Two acceptable paths:
+
+1) **Proposal-style backport**: write plan content into the design doc as "Proposed Design Change" and mark it as needing decision/confirmation;
+
+2) **Defer**: mark plan items as `DEFERRED/UNSCOPED` until design is clarified.
+
+- When backporting, explicitly label it as "new design decision/supplemental constraint" and explain reasons and impact scope.
+
+---
+
+## Output Requirements
+
+1. **Diff checklist**: list "plan exceeds design" candidate items (group by plan ID), with classification: `Design-level / Implementation-level / Out-of-scope`.
+
+2. **Design backport patch**: write all `Design-level` content back into the design doc with minimal edits, placed in the most appropriate sections (e.g., non-goals/design principles/risks & fallback/contracts/milestones/key decisions).
+
+3. **Traceability updates**: for each backported design item, state acceptance method (A/B/C) and acceptance anchors, and require updates to:
+   - Traceability matrix (prefer updating `<change-root>/<change-id>/verification.md`; sync to `docs/` only if needed externally)
+   - Manual acceptance checklist (prefer updating `MANUAL-*` in `<change-root>/<change-id>/verification.md`; sync to `docs/` only if needed externally)
+   - If new/updated automation anchors are needed: list tests/static checks to add (tests/commands/markers)
+
+---
+
+## Ready-to-Copy Prompt
+
+```text
+You are the "Design Doc Editor." Your goal is to backport design-level content from the implementation plan into the design doc, making it traceable and verifiable.
+
+Inputs:
+
+- Design doc: `<change-root>/<change-id>/design.md` (or an equivalent path you provide)
+- Implementation plan: `<change-root>/<change-id>/tasks.md` (or an equivalent path you provide)
+
+Tasks:
+
+1) Read the implementation plan and identify all items that are missing or under-specified in the design doc (group by section).
+
+2) Classify each candidate item:
+
+- Design-level (should be backported): impacts external semantics/user flows/system red lines/data contracts/evolution strategy/operations/governance/key decisions
+- Implementation-level (do not backport): implementation details, file paths, PR splitting, execution order, pseudocode details
+- Out-of-scope (do not backport and defer): not in scope or future phase not yet confirmed by design
+
+3) For Design-level items only, backport into the design doc:
+
+- Place in the most appropriate existing section; add small sections if needed, but do not restructure the whole doc
+- Write in "design constraints/decisions" tone; avoid implementation detail
+- If it conflicts with existing design: do not overwrite conclusions; add a "Proposed Design Change/Open Question" with reason, impact, and decision points
+- Update the design doc's "last updated" metadata (if present)
+
+4) Output:
+
+- A) Candidate list with classifications (by plan ID)
+- B) Minimal patch to the design doc (only added/modified paragraphs)
+- C) Traceability and anchor updates (prioritized):
+  - Which tests/static checks to add/update (A-class anchors)
+  - Which manual/hybrid acceptance items to add/update (B/C anchors, prefer `<change-root>/<change-id>/verification.md`)
+  - How to update the traceability matrix (prefer `<change-root>/<change-id>/verification.md`)
+
+Constraints:
+
+- Do not write file paths, class/function names, DB table names, or other implementation details into the design doc unless they are stable architectural boundaries.
+- Do not paste large pseudocode blocks; you may state invariants, complexity limits, and fallback strategies.
+- Keep language consistent with the design doc (English by default; include domain terms if needed).
+```