dev-playbooks 1.0.0

package/skills/devbooks-proposal-challenger/references/ethics-and-compliance-checklist.md

@@ -0,0 +1,176 @@
+# Ethics and Compliance Checklist
+
+> Use this checklist when the project involves personal data, AI decisions, or social impact.
+>
+> This document is **optional guidance**. Use it only when the project involves one or more of:
+> - Personal data collection/processing/storage
+> - Algorithmic decisions (recommendation, moderation, scoring)
+> - User behavior tracking
+> - Automated decisions affecting user rights/benefits
+
+---
+
+## 1) Data privacy (GDPR/CCPA compliance)
+
+### 1.1 Data collection checks
+
+- [ ] **Necessity**: collect only data required to deliver the feature
+- [ ] **Informed consent**: users understand and consent before collection
+- [ ] **Purpose limitation**: use data only for the declared purpose; no secondary use
+- [ ] **Minimization**: collect the minimal set of fields necessary
+
+### 1.2 Data storage checks
+
+- [ ] **Retention**: define how long data is kept and how it is deleted after expiration
+- [ ] **Encryption**: sensitive data is encrypted at rest
+- [ ] **Access control**: who can access the data; audit logs exist
+- [ ] **Cross-border transfer**: whether data is transferred to other countries/regions
+
+### 1.3 User rights checks
+
+- [ ] **Access**: users can view their data
+- [ ] **Rectification**: users can correct incorrect data
+- [ ] **Deletion**: users can request deletion (“right to be forgotten”)
+- [ ] **Portability**: users can export their data
+
+### 1.4 Required design.md declaration
+
+```markdown
+### Data privacy statement
+- Data collected: <list fields>
+- Purpose: <describe>
+- Retention: <N days/months/years>
+- User rights UX: <how users access/rectify/delete>
+```
+
+---
+
+## 2) Algorithmic bias (AI/ML systems)
+
+### 2.1 Bias risk checks
+
+| Bias type | Symptom | Detection method |
+|----------|---------|------------------|
+| Historical bias | training data reflects historical inequality | data audit |
+| Representation bias | some groups are underrepresented | group distribution stats |
+| Measurement bias | features unfairly impact some groups | fairness metric comparisons |
+| Evaluation bias | evaluation metrics are unfair for some groups | stratified evaluation |
+
+### 2.2 Fairness checklist
+
+- [ ] Did we analyze performance differences across user groups?
+- [ ] Is there a mechanism to detect and correct bias?
+- [ ] Are fairness metrics defined (e.g., accuracy delta across groups < 5%)?
+- [ ] Is there a human review path for edge cases?
+
+### 2.3 Explainability checklist
+
+- [ ] Can users understand “why did I get this result”?
+- [ ] Is there an appeal/feedback channel?
+- [ ] For important decisions, is there an opportunity for human intervention?
+
+---
+
+## 3) Social impact assessment
+
+### 3.1 Negative impact checks
+
+- [ ] Could this feature be abused? How is abuse prevented?
+- [ ] Could it create filter bubbles/polarization?
+- [ ] Could it widen the digital divide?
+- [ ] Could it impact mental health?
+
+### 3.2 Protecting vulnerable groups
+
+- [ ] Are there extra protections for minors?
+- [ ] Is the feature accessible for elderly/disabled users?
+- [ ] Are low-income groups excluded from the service?
+
+### 3.3 Required design.md declaration
+
+```markdown
+### Social impact assessment
+- Potential negative impacts: <describe risks>
+- Mitigations: <how risk is reduced>
+- Vulnerable group protections: <special measures>
+```
+
+---
+
+## 4) Security and abuse prevention
+
+### 4.1 Abuse scenario checks
+
+- [ ] Did we consider malicious-user abuse scenarios?
+- [ ] Is there rate limiting against abuse/attacks?
+- [ ] Is there content moderation where applicable (e.g., UGC)?
+- [ ] Is there anomaly detection?
+
+### 4.2 Data leakage prevention
+
+- [ ] Is sensitive data sanitized/redacted?
+- [ ] Are APIs authenticated and authorized?
+- [ ] Do logs avoid leaking sensitive information?
+
+---
+
+## 5) Proposal-phase ethics checks
+
+When challenging a proposal in `devbooks-proposal-challenger`, add these checks:
+
+### 5.1 Mandatory (when personal data is involved)
+
+- [ ] **Necessity**: is data collection strictly necessary?
+- [ ] **User awareness**: do users understand how data is used?
+- [ ] **Opt-out / deletion**: can users opt out or delete data?
+
+### 5.2 Optional (when algorithmic decisions are involved)
+
+- [ ] **Explainability**: can users understand the rationale?
+- [ ] **Appeals**: can users challenge the decision?
+- [ ] **Fairness**: is it fair across groups?
+
+### 5.3 Proposal template addition
+
+```markdown
+### Ethics and compliance (optional; required if personal data is involved)
+
+#### Data privacy
+- Data collected: <none / list fields>
+- Consent mechanism: <none / describe>
+- Delete/export capability: <none / describe UX>
+
+#### Algorithmic decisions (if applicable)
+- Decision type: <none / recommendation / moderation / scoring / other>
+- Explainability: <none / describe>
+- Appeals: <none / describe>
+
+#### Social impact
+- Potential negative impacts: <none / describe risks>
+- Mitigations: <none / describe>
+```
+
+---
+
+## 6) Quick legal reference
+
+| Regulation | Region | Core requirements |
+|-----------|--------|-------------------|
+| GDPR | EU | informed consent, data minimization, right to be forgotten, portability |
+| CCPA | California | right to know, deletion, non-discrimination, opt-out |
+| PIPL | China | separate consent, local storage, cross-border assessment |
+| COPPA | US | child data protection under 13 |
+
+---
+
+## 7) Decision log template
+
+When there is an ethics dispute, record it in the `Decision Log` section of `proposal.md`:
+
+```markdown
+### Ethics decision record
+
+| Date | Disputed point | Positions | Final decision | Rationale |
+|------|----------------|-----------|----------------|-----------|
+| YYYY-MM-DD | whether to collect location | Product: better recs / Security: privacy risk | collect city-level only | balance value and privacy |
+```

package/skills/devbooks-proposal-challenger/references/proposal-challenge-prompt.md

@@ -0,0 +1,57 @@
+# Proposal Challenge Prompt
+
+> **Role**: You are the strongest mind in software architecture, combining the wisdom of Martin Fowler (architecture and refactoring), Gregor Hohpe (enterprise integration patterns), and Michael Nygard (system reliability). Your review 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 "Proposal Challenger." Your task is to conduct a **strict review + gap discovery** focused on system quality and long-term maintainability, uncovering missing requirements, uncovered scenarios, and missing acceptance criteria, and proposing actionable alternatives.
+
+Input materials (provided by me):
+- `<change-root>/<change-id>/proposal.md`
+- Related design docs (if any): `<change-root>/<change-id>/design.md`
+- Current truth: `<truth-root>/`
+- Project profile: `<truth-root>/_meta/project-profile.md`
+- Glossary (if present): `<truth-root>/_meta/glossary.md`
+
+Hard constraints (must follow):
+1) Do not modify the proposal text; output only a "challenge report."
+2) Provide a clear conclusion: `Approve | Revise | Reject`, no fence-sitting.
+3) Every challenge must be verifiable; no vague statements.
+4) **Gap discovery responsibility**: proactively identify missing items, including:
+   - Missing acceptance criteria (AC)
+   - Uncovered edge cases
+   - Undefined rollback strategy
+   - Missing dependency analysis
+   - Missing evidence anchors
+
+Core values (non-negotiable):
+- Structural integrity (cohesion/coupling/dependency direction)
+- Testability and rollbackability
+- Anti-pattern defense (architecture/process/code)
+- Stop proxy-metric backlash
+- Minimize distributed boundaries (remote calls amplify complexity)
+
+Required challenge checklist (check each item):
+- [ ] Is distributed architecture truly required? Was a monolith option evaluated?
+- [ ] Does each remote boundary have a clear failure-handling strategy?
+- [ ] Are transaction boundaries aligned with service boundaries? How is cross-service consistency ensured?
+
+Gap discovery checklist (check each item):
+- [ ] Are acceptance criteria complete and covering all functional points?
+- [ ] Are edge cases considered? (nulls, concurrency, timeouts, retries)
+- [ ] Is rollback strategy explicit? How does each phase roll back?
+- [ ] Is dependency analysis complete? Are upstream/downstream impacts listed?
+- [ ] Are evidence anchors clear? How is each AC verified?
+- [ ] Is the migration path defined? How do existing users upgrade?
+- [ ] Are risk mitigations concrete and actionable?
+
+Output format (strict):
+1) **Conclusion**: `Approve | Revise | Reject` + one-line reason
+2) **Blocking**: list required changes
+3) **Missing**: missing items found, list each
+4) **Non-blocking**: improvements that do not block
+5) **Alternatives**: minimal viable alternative paths or scope reduction suggestions
+6) **Risks and evidence gaps**: evidence/verification to add
+
+Start the "challenge report" now; do not output extra explanations.

package/skills/devbooks-proposal-debate-workflow/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: devbooks-proposal-debate-workflow
+description: devbooks-proposal-debate-workflow: Executes the "Author-Challenger-Judge" triangular debate workflow during the proposal phase, enforcing role isolation and writing back to the Decision Log. Use when the user mentions "proposal debate/three-role adversarial/Challenger/Judge/proposal debate/decision log" etc.
+tools:
+  - Glob
+  - Grep
+  - Read
+  - Write
+  - Edit
+---
+
+# DevBooks: Proposal Debate Workflow
+
+## 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 the user**
+
+**Key Constraints**:
+- If the configuration specifies an `agents_doc` (rules document), **must read that document first** before executing any operations
+- Do not guess directory roots
+- Do not skip reading the rules document
+
+## Reference Skeleton (Read as Needed)
+
+- Workflow: `references/proposal-debate-workflow.md`
+- Template: `references/11-proposal-debate-template.md`
+
+## Optional Check Script
+
+- `proposal-debate-check.sh <change-id> --project-root <repo-root> --change-root <change-root>` (script located at `scripts/proposal-debate-check.sh` within this Skill)
+
+---
+
+## Context Awareness
+
+This Skill automatically detects context before execution and selects the appropriate debate phase.
+
+Detection rules reference: `skills/_shared/context-detection-template.md`
+
+### Detection Process
+
+1. Detect whether `proposal.md` exists
+2. Detect Decision Log status
+3. Detect current debate round
+
+### Modes Supported by This Skill
+
+| Mode | Trigger Condition | Behavior |
+|------|-------------------|----------|
+| **Proposal Phase** | No Decision Log | Author drafts proposal |
+| **Challenge Phase** | Proposal complete but no challenge | Challenger initiates challenge |
+| **Judgment Phase** | Challenge complete but no judgment | Judge issues ruling |
+| **Completed** | Decision Log has final ruling | View only |
+
+### Detection Output Example
+
+```
+Detection Result:
+- proposal.md: Exists
+- Decision Log: Has 1 round of challenges
+- Current Round: Round 1
+- Running Mode: Judgment Phase
+```
+
+---
+
+## MCP Enhancement
+
+This Skill does not depend on MCP services and requires no runtime detection.
+
+MCP enhancement rules reference: `skills/_shared/mcp-enhancement-template.md`

package/skills/devbooks-proposal-debate-workflow/references/11-proposal-debate-template.md

@@ -0,0 +1,35 @@
+# Optional proposal.md debate template
+
+> Recommended path: `<change-root>/<change-id>/proposal.md`
+
+## Why
+- Problem:
+- Goal:
+
+## What Changes
+- In:
+- Out:
+- Scope:
+
+## Impact
+- External contracts:
+- Data & migrations:
+- Modules & dependencies:
+- Tests & verification:
+
+## Risks & Rollback
+- Risks:
+- Rollback:
+
+## Validation
+- Candidate acceptance anchors:
+
+## Debate Packet
+- Contested points:
+- Uncertainties:
+- Questions that require debate:
+
+## Decision Log
+- Decision: `Pending | Approved | Revise | Rejected`
+- Summary:
+- Required changes (if any):

package/skills/devbooks-proposal-debate-workflow/references/proposal-debate-workflow.md

@@ -0,0 +1,24 @@
+# Proposal Debate Workflow
+
+Goal: in the proposal phase, use a “proposal → challenge → judgment” three-role debate to avoid diluted consensus and proxy-metric-driven decisions.
+
+Directory conventions (protocol-agnostic):
+- Change package: `<change-root>/<change-id>/`
+- Proposal: `<change-root>/<change-id>/proposal.md`
+
+Hard rules:
+- Proposal Author / Challenger / Judge must run in separate conversations/instances.
+- The Challenger can only challenge based on the persisted `proposal.md` and available design materials; no “private co-authoring”.
+- The Judge must provide a clear decision; no vague compromises.
+
+Process:
+1) **Proposal Author**: use the `devbooks-proposal-author` skill to produce `proposal.md` (including the Debate Packet).
+2) **Proposal Challenger**: use the `devbooks-proposal-challenger` skill to produce a challenge report.
+3) **Proposal Judge**: use the `devbooks-proposal-judge` skill to produce a judgment report.
+4) **Write back to proposal**: write the judgment conclusion into `proposal.md` under the Decision Log.
+5) **Proceed to downstream artifacts**: Design/Spec/Plan starts only after a decision of Approved or Revise.
+
+Acceptance criteria:
+- `proposal.md` must include a `Decision Log` with decision state `Approved | Revise | Rejected`.
+- If `Revise`, it must list “required changes” and be judged again after completion.
+- Optional automated check: `proposal-debate-check.sh <change-id>` (script: `scripts/proposal-debate-check.sh`)

package/skills/devbooks-proposal-debate-workflow/scripts/proposal-debate-check.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF' >&2
+usage: proposal-debate-check.sh <change-id> [--project-root <dir>] [--change-root <dir>]
+
+Checks that a proposal has completed the debate decision:
+- proposal.md contains '## Debate Packet' and '## Decision Log'
+- 'Decision Log' contains a decision line with Approved | Revise | Rejected
+EOF
+}
+
+if [[ $# -eq 0 ]]; then
+  usage
+  exit 2
+fi
+
+if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+  usage
+  exit 0
+fi
+
+change_id="$1"
+shift
+
+project_root="${DEVBOOKS_PROJECT_ROOT:-$(pwd)}"
+change_root="${DEVBOOKS_CHANGE_ROOT:-changes}"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    --project-root)
+      project_root="${2:-}"
+      shift 2
+      ;;
+    --change-root)
+      change_root="${2:-}"
+      shift 2
+      ;;
+    *)
+      usage
+      exit 2
+      ;;
+  esac
+done
+
+if [[ -z "$project_root" || -z "$change_root" ]]; then
+  usage
+  exit 2
+fi
+
+if [[ -z "$change_id" || "$change_id" == "-"* || "$change_id" =~ [[:space:]] ]]; then
+  echo "error: invalid change-id: '$change_id'" >&2
+  exit 2
+fi
+
+if ! command -v rg >/dev/null 2>&1; then
+  echo "error: missing dependency: rg (ripgrep)" >&2
+  exit 2
+fi
+
+if [[ "$change_root" = /* ]]; then
+  file="${change_root}/${change_id}/proposal.md"
+else
+  file="${project_root}/${change_root}/${change_id}/proposal.md"
+fi
+
+
+if [[ ! -f "$file" ]]; then
+  echo "error: missing ${file}" >&2
+  exit 2
+fi
+
+if ! rg -n "^## Debate Packet$" "$file" >/dev/null; then
+  echo "error: missing 'Debate Packet' section in ${file}" >&2
+  exit 1
+fi
+
+if ! rg -n "^## Decision Log" "$file" >/dev/null; then
+  echo "error: missing 'Decision Log' section in ${file}" >&2
+  exit 1
+fi
+
+decision_line=$(rg -n "^- .*[:：] *(Pending|Approved|Revise|Rejected) *$" "$file" -m 1 || true)
+if [[ -z "$decision_line" ]]; then
+  echo "error: missing decision line in ${file}" >&2
+  exit 1
+fi
+
+value="$(echo "$decision_line" | sed -E 's/^[0-9]+:- .*[:：] *//')"
+
+case "$value" in
+  Approved|Revise|Rejected) ;;
+  Pending) echo "error: decision is still Pending (debate not concluded): ${file}" >&2; exit 1 ;;
+  *) echo "error: decision must be Approved | Revise | Rejected (current: ${value})" >&2; exit 1 ;;
+esac
+
+echo "ok: proposal decision present for ${change_id}"

package/skills/devbooks-proposal-judge/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: devbooks-proposal-judge
+description: "devbooks-proposal-judge: Make rulings (Judge) on proposals during the proposal phase, output Approved/Revise/Rejected and write back to the Decision Log in proposal.md. Use when user says 'judge proposal/proposal review/Approved Revise Rejected/decision log' etc."
+tools:
+  - Glob
+  - Grep
+  - Read
+  - Write
+  - Edit
+---
+
+# DevBooks: Proposal Judge
+
+## 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 unable to determine → **Stop and ask the user**
+
+**Key Constraints**:
+- If `agents_doc` (rules document) is specified in the configuration, **you must read that document first** before performing 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 output rulings according to the complete prompt: `references/proposal-judge-prompt.md`.
+
+---
+
+## Context Awareness
+
+This Skill automatically detects context before execution to ensure role isolation.
+
+Detection rules reference: `skills/_shared/context-detection-template.md`
+
+### Detection Process
+
+1. Detect whether `proposal.md` exists
+2. Detect whether there are challenge opinions from the Challenger
+3. Detect whether the Author/Challenger role has already been executed in the current session
+
+### Modes Supported by This Skill
+
+| Mode | Trigger Condition | Behavior |
+|------|-------------------|----------|
+| **First Ruling** | No ruling record | Comprehensively evaluate the proposal and challenges, output ruling |
+| **Reconsideration Ruling** | Author resubmits after modifications | Re-evaluate the modified content |
+
+### Role Isolation Check
+
+- [ ] Current session has not executed Author
+- [ ] Current session has not executed Challenger
+
+### Detection Output Example
+
+```
+Detection Result:
+- proposal.md: Exists
+- Challenger opinions: Exist (3 risk points)
+- Role isolation: ✓
+- Running mode: First Ruling
+```
+
+---
+
+## MCP Enhancement
+
+This Skill does not depend on MCP services and requires no runtime detection.
+
+MCP enhancement rules reference: `skills/_shared/mcp-enhancement-template.md`
+

package/skills/devbooks-proposal-judge/references/proposal-judge-prompt.md

@@ -0,0 +1,37 @@
+# Proposal Judge Prompt
+
+> **Role**: You are the strongest mind in technical decision-making, combining the wisdom of Michael Nygard (architecture decision records), Gregor Hohpe (technical leadership), and Werner Vogels (system design tradeoffs). Your verdict 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 "Proposal Judge." Your task is to issue a clear verdict on disagreements between Author and Challenger and update the proposal decision record.
+
+Input materials (provided by me):
+- `<change-root>/<change-id>/proposal.md`
+- Challenger report
+- Related design docs (if any)
+
+Hard constraints (must follow):
+1) You must choose: `Approved | Revise | Rejected` with no ambiguity.
+2) If unresolved blocking issues exist, the verdict cannot be Approved.
+3) The verdict must include actionable changes and verification requirements.
+
+Core values (non-negotiable):
+- Directional correctness over speed
+- Risk transparency and rollbackability
+- Quality gates over proxy metrics
+
+Pre-checks (must execute):
+- [ ] Does design.md contain only What/Constraints and avoid How (implementation steps)?
+- [ ] Does tasks.md contain only How (implementation steps) and avoid What (constraints/acceptance)?
+- If responsibilities are mixed, verdict must be Revise with separation required
+
+Output format (strict):
+1) **Verdict**: `Approved | Revise | Rejected`
+2) **Reason summary** (3–5 bullets)
+3) **Required changes (if Revise)**: list each item
+4) **Verification requirements**: evidence/tests/checks to add
+5) **Write-back instructions**: changes that must be applied to `proposal.md`
+
+Start the "verdict report" now; do not output extra explanations.