dev-playbooks 1.7.3 → 2.0.0

package/README.md

@@ -31,6 +31,39 @@ AI coding assistants are powerful, but often **unpredictable**:
 
 ---
 
+## ✨ v2.0.0 New Features: Human-Friendly Document Templates
+
+**Core Philosophy**: In the AI era, humans need concise information to make decisions, not reading thousands of lines of AI-generated documents.
+
+### Bottom Line Up Front (30-second understanding)
+
+Every document (proposal, design, tasks, verification) has a brief summary at the top:
+- ✅ **What will result**: List changes in plain language
+- ❌ **What won't result**: Clearly state what won't change
+- 📝 **One-sentence summary**: Understandable even for non-technical people
+
+### Alignment Check (Uncover hidden requirements)
+
+In the proposal phase, guide users through questions:
+- 👤 **Who are you?**: Quick Starter / Platform Builder / Rapid Validator
+- 🎯 **What do you want?**: Explicit requirements + hidden requirements
+- 💡 **Multi-perspective recommendations**: Different recommendations based on different roles
+
+### Default Approval Mechanism (Reduce decision fatigue)
+
+- ⏰ **User silence = agreement**: Auto-approve after timeout
+- 🎛️ **Configurable timeout**: proposal 48h / design 24h / tasks 24h / verification 12h
+- 🔒 **Retain control**: Users can reject or customize at any time
+
+### Project-Level Documents (Knowledge retention)
+
+- 📋 **User Profile** (project-profile.md): Record role, requirements, constraints, preferences
+- 📝 **Decision Log** (decision-log.md): Record all important decisions for retrospection
+
+**See**: `docs/v2.0.0-changelog.md`
+
+---
+
 ## How It Works
 
 **Hard constraint**: Test Owner and Coder **must work in separate conversations**. This is not a suggestion. Coder cannot modify `tests/**`. "Done" is defined by tests/build verification, not AI self-evaluation.

package/package.json

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

package/skills/Skill-Development-Guide.md

@@ -37,9 +37,9 @@ This document defines the design principles and constraints you must follow when
 **Editor Skills MUST**:
 - [ ] Back up original files before edits (or make it recoverable via git)
 - [ ] Avoid cumulative side effects across reruns
-- [ ] Provide a “dry-run” mode to preview changes
+- [ ] Provide a "dry-run" mode to preview changes
 
-### 1.3 Verification-First Principle (inspired by VS Code)
+### 1.3 Verification-First Principle
 
 **Core requirement**: after a generator/editor Skill writes files, it **must run verification**, and must not proceed to the next step if verification fails.
 
@@ -99,7 +99,7 @@ echo "ok: verification passed"
 - **Write to workspace**: Skills should write to `<change-root>/<change-id>/`.
 - **Archive is merge**: archiving merges workspace outputs back into truth.
 
-### 1.6 Resource Cleanup (inspired by VS Code)
+### 1.6 Resource Cleanup
 
 **Requirement**: clean up temporary resources on both success and failure.
 

package/skills/_shared/references/approval-configuration-guide.md

@@ -0,0 +1,285 @@
+# Approval Configuration Guide
+
+> This document explains how to configure the approval mechanism, including default approval, timeout settings, etc.
+
+## Configuration File Location
+
+```
+.devbooks/config.yaml
+```
+
+## Configuration Example
+
+```yaml
+# Approval configuration
+approval:
+  # Default approval strategy
+  # - auto_approve: Auto-approve after timeout (default)
+  # - require_explicit: Must explicitly approve
+  # - disabled: Disable approval mechanism
+  default_strategy: auto_approve
+
+  # Timeout (hours)
+  timeout:
+    proposal: 48      # Proposal needs 48 hours
+    design: 24        # Design needs 24 hours
+    tasks: 24         # Tasks needs 24 hours
+    verification: 12  # Verification needs 12 hours
+
+  # Whether explicit approval is required
+  require_explicit:
+    proposal: true    # Proposal must be explicitly approved
+    design: false     # Design can be auto-approved
+    tasks: false      # Tasks can be auto-approved
+    verification: false  # Verification can be auto-approved
+
+  # Approval methods
+  approval_methods:
+    - cli           # Command-line approval
+    - chat          # Chat approval
+    - auto          # Auto-approval
+
+  # Notification methods
+  notification:
+    - terminal      # Terminal notification
+    # - desktop     # Desktop notification (optional)
+    # - email       # Email notification (optional)
+```
+
+## Configuration Details
+
+### 1. Default Approval Strategy
+
+| Strategy | Description | Use Case |
+|----------|-------------|----------|
+| `auto_approve` | Auto-approve after timeout | Most cases (recommended) |
+| `require_explicit` | Must explicitly approve | High-risk projects |
+| `disabled` | Disable approval mechanism | Complete trust in AI |
+
+### 2. Timeout Settings
+
+- **Proposal**: 48 hours (needs more time to think)
+- **Design**: 24 hours (technical details)
+- **Tasks**: 24 hours (task breakdown)
+- **Verification**: 12 hours (acceptance results)
+
+**Recommendations**:
+- Personal projects: Can shorten timeout (e.g., 12/6/6/3 hours)
+- Team projects: Keep default timeout
+- High-risk projects: Extend timeout (e.g., 72/48/48/24 hours)
+
+### 3. Explicit Approval Required
+
+- **true**: Must explicitly approve, won't auto-approve
+- **false**: Auto-approve after timeout
+
+**Recommendations**:
+- Set Proposal to true (important decisions)
+- Set other phases to false (reduce burden)
+
+### 4. Approval Methods
+
+#### CLI Approval
+
+```bash
+# Approve
+devbooks approve <change-id> --stage proposal
+
+# Reject
+devbooks reject <change-id> --stage proposal --reason "reason"
+
+# Revise
+devbooks revise <change-id> --stage proposal
+```
+
+#### Chat Approval
+
+Say directly in chat:
+- "agree" / "approve"
+- "disagree" / "reject"
+- "I want to modify XXX"
+
+#### Auto-approval
+
+Auto-approve after timeout (based on configuration)
+
+### 5. Notification Methods
+
+- **terminal**: Terminal notification (default)
+- **desktop**: Desktop notification (requires additional configuration)
+- **email**: Email notification (requires additional configuration)
+
+## Approval Process
+
+### 1. Creation Phase
+
+After AI creates a document, it adds an approval block at the end:
+
+```markdown
+## ✅ Approval Process
+
+**Current status**:
+- 📝 Status: Pending approval
+- ⏰ Created at: 2026-01-19 10:00
+- ⏰ Timeout at: 2026-01-20 10:00 (after 24 hours)
+
+**If you agree**:
+- [ ] ✅ Approve, start next phase
+
+**If you disagree**:
+- [ ] ❌ Reject, explain reason
+
+**Default choice**: ✅ Approve (auto-approved after 24 hours)
+```
+
+### 2. Notification Phase
+
+System reminds users through configured notification methods:
+
+```
+⏰ Reminder: Proposal pending approval
+- Change: 20260119-1000-add-feature-x
+- Phase: Proposal
+- Timeout at: 2026-01-20 10:00 (23 hours remaining)
+- Action: devbooks approve 20260119-1000-add-feature-x --stage proposal
+```
+
+### 3. Approval Phase
+
+Users can approve through:
+
+- **CLI**: `devbooks approve <change-id> --stage proposal`
+- **Chat**: Say "agree" directly
+- **Auto**: Do nothing, wait for timeout
+
+### 4. Timeout Phase
+
+If timeout and configured as `auto_approve`, system auto-approves:
+
+```
+✅ Auto-approved: Proposal
+- Change: 20260119-1000-add-feature-x
+- Phase: Proposal
+- Reason: Auto-approved after timeout (24 hours)
+```
+
+### 5. Recording Phase
+
+All approval actions are recorded in approval history:
+
+```markdown
+## Approval History
+
+| Time | Phase | Action | Actor | Reason |
+|------|-------|--------|-------|--------|
+| 2026-01-19 10:00 | Proposal | Created | AI | - |
+| 2026-01-20 10:00 | Proposal | Auto-approved | System | 24-hour timeout |
+```
+
+## FAQ
+
+### Q1: How to disable auto-approval?
+
+Modify configuration file:
+
+```yaml
+approval:
+  default_strategy: require_explicit
+  require_explicit:
+    proposal: true
+    design: true
+    tasks: true
+    verification: true
+```
+
+### Q2: How to shorten timeout?
+
+Modify configuration file:
+
+```yaml
+approval:
+  timeout:
+    proposal: 12
+    design: 6
+    tasks: 6
+    verification: 3
+```
+
+### Q3: How to view pending approvals?
+
+```bash
+devbooks status
+```
+
+Output:
+
+```
+Pending approvals:
+- 20260119-1000-add-feature-x (Proposal, 23 hours remaining)
+- 20260119-1100-fix-bug-y (Design, 5 hours remaining)
+```
+
+### Q4: How to batch approve?
+
+```bash
+devbooks approve --all
+```
+
+### Q5: How to revoke approval?
+
+```bash
+devbooks revoke <change-id> --stage proposal
+```
+
+## Best Practices
+
+### 1. Personal Projects
+
+```yaml
+approval:
+  default_strategy: auto_approve
+  timeout:
+    proposal: 12
+    design: 6
+    tasks: 6
+    verification: 3
+  require_explicit:
+    proposal: false
+    design: false
+    tasks: false
+    verification: false
+```
+
+### 2. Team Projects
+
+```yaml
+approval:
+  default_strategy: auto_approve
+  timeout:
+    proposal: 48
+    design: 24
+    tasks: 24
+    verification: 12
+  require_explicit:
+    proposal: true
+    design: false
+    tasks: false
+    verification: false
+```
+
+### 3. High-risk Projects
+
+```yaml
+approval:
+  default_strategy: require_explicit
+  timeout:
+    proposal: 72
+    design: 48
+    tasks: 48
+    verification: 24
+  require_explicit:
+    proposal: true
+    design: true
+    tasks: true
+    verification: true
+```

package/skills/_shared/references/document-template-decision-log.md

@@ -0,0 +1,137 @@
+# Decision Log Document Template
+
+> This template defines the standard structure for decision-log.md, used to record all important decisions for easy retrospection and learning.
+
+## File Location
+
+```
+<truth-root>/specs/_meta/decision-log.md
+```
+
+## Standard Structure
+
+```markdown
+# Decision Log: <Project Name>
+
+> **Purpose**: Record all important decisions for easy retrospection and learning
+
+## Decision #001: [Decision Title]
+
+**Decision time**: YYYY-MM-DD
+**Decision phase**: Proposal / Design / Tasks / Verification
+**Decision maker**: User / AI recommendation / Default
+
+**Background**:
+[Why this decision needs to be made]
+
+**Options**:
+- Option A: [Description]
+  - Advantages: [Advantages]
+  - Disadvantages: [Disadvantages]
+  - Suitable for: [What scenarios]
+
+- Option B: [Description]
+  - Advantages: [Advantages]
+  - Disadvantages: [Disadvantages]
+  - Suitable for: [What scenarios]
+
+**Decision**:
+Choose option [X]
+
+**Reason**:
+- [Reason 1]
+- [Reason 2]
+- [Reason 3]
+
+**Impact**:
+- ✅ [Positive impact]
+- ⚠️ [Negative impact]
+- ⚠️ [Risk]
+
+**Subsequent evolution**:
+- YYYY-MM-DD: [Evolution record]
+
+---
+
+## Decision #002: [Decision Title]
+
+...
+
+---
+
+## Decision Template
+
+**Decision #XXX: [Decision Title]**
+
+**Decision time**: YYYY-MM-DD
+**Decision phase**: Proposal / Design / Tasks / Verification
+**Decision maker**: User / AI recommendation / Default
+
+**Background**:
+[Why this decision needs to be made]
+
+**Options**:
+- Option A: [Description]
+- Option B: [Description]
+- Option C: [Description]
+
+**Decision**:
+Choose option X
+
+**Reason**:
+- [Reason 1]
+- [Reason 2]
+- [Reason 3]
+
+**Impact**:
+- ✅ [Positive impact]
+- ⚠️ [Negative impact]
+- ⚠️ [Risk]
+
+**Subsequent evolution**:
+- YYYY-MM-DD: [Evolution record]
+```
+
+## Usage Guide
+
+### 1. Who writes Decision Log?
+
+- **proposal-author**: Records decisions from Proposal phase
+- **design-doc**: Records decisions from Design phase
+- **implementation-plan**: Records decisions from Tasks phase
+- **archiver**: Organizes decision log during archiving
+
+### 2. Who reads Decision Log?
+
+| Skill | Reading Purpose |
+|-------|-----------------|
+| proposal-author | Understand historical decisions, avoid repeated discussions |
+| design-doc | Understand historical reasons for technology selection |
+| impact-analysis | Assess long-term impact of decisions |
+| archiver | Organize decision log, build knowledge base |
+
+### 3. Purpose of Decision Log
+
+- **Knowledge retention**: Record background, reasons, and impact of decisions
+- **Avoid repetition**: Avoid repeated discussions of the same issues
+- **Learning and improvement**: Review subsequent evolution of decisions, learn lessons
+- **Team collaboration**: Help new members quickly understand project's decision history
+
+### 4. Decision Log Update Frequency
+
+- **Real-time updates**: Record immediately when important decisions are made
+- **Regular review**: Review monthly, update "Subsequent evolution" section
+- **Archiving organization**: Organize decision log during each archiving, remove outdated decisions
+
+### 5. What decisions need to be recorded?
+
+**Decisions to record**:
+- Technology selection (choosing A over B)
+- Architecture design (choosing solution A over solution B)
+- Important trade-offs (sacrificing X for Y)
+- Boundary conditions (explicitly not doing something)
+
+**Decisions not to record**:
+- Obvious decisions (like using Git for version control)
+- Temporary decisions (like variable naming)
+- Reversible decisions (like code formatting)

package/skills/_shared/references/document-template-design.md

@@ -0,0 +1,202 @@
+# Design Document Template
+
+> This template defines the standard structure for design.md to ensure designs are clear, implementable, and verifiable.
+
+## File Location
+
+```
+<change-root>/<change-id>/design.md
+```
+
+## Standard Structure
+
+```markdown
+# <Change Title> - Design Document
+
+## 🎯 Bottom Line Up Front (30-second read)
+
+**This design will result in**:
+- ✅ [Change 1 that will happen]
+- ✅ [Change 2 that will happen]
+- ✅ [Change 3 that will happen]
+
+**This design will NOT result in**:
+- ❌ [What won't happen 1]
+- ❌ [What won't happen 2]
+
+**Difference from Proposal**:
+- 📝 Proposal said "[Proposal content]"
+- 🎨 Design says "[Specific implementation approach]"
+
+---
+
+## 🤔 Requirements Alignment Check (2-minute read)
+
+> Purpose: Confirm the design meets your needs
+
+### Quick Check
+
+**In the Proposal phase you chose**:
+- Role: [Role name]
+- Solution: [Solution name]
+
+**Changes in the Design phase**:
+- ⚠️ [New issues or constraints discovered]
+- ✅ [Suggested adjustments]
+- ⚠️ Trade-offs: [Explain trade-offs]
+
+**Need your confirmation**:
+- [ ] ✅ Agree with adjustments ([reason])
+- [ ] ❌ Disagree, continue with original plan ([reason])
+- [ ] 🤔 I need more information
+
+**Default choice**: ✅ Agree with adjustments (auto-approved after 24 hours)
+
+---
+
+## ✅ Approval Process (1 minute)
+
+**Current status**:
+- 📝 Status: Pending approval
+- ⏰ Created at: [time]
+- ⏰ Timeout at: [time] (after 24 hours)
+
+**If you agree**:
+- [ ] ✅ Approve design, start implementation
+
+**If you disagree**:
+- [ ] ❌ Reject design, reason: [reason]
+
+**Default choice**: ✅ Approve design (auto-approved after 24 hours)
+
+---
+
+## 📋 Detailed Design (AI reading)
+
+### What (What to do)
+
+#### Objective
+
+[Describe the design objective]
+
+#### Scope
+
+[Explain the design scope]
+
+---
+
+### Constraints
+
+#### Technical Constraints
+
+| Constraint | Description | Impact |
+|------------|-------------|--------|
+| [Constraint1] | [Description] | [Impact] |
+
+#### Business Constraints
+
+| Constraint | Description | Impact |
+|------------|-------------|--------|
+| [Constraint1] | [Description] | [Impact] |
+
+---
+
+### Architecture
+
+#### Component Diagram
+
+```
+[Use Mermaid or text to describe component relationships]
+```
+
+#### Data Flow
+
+```
+[Describe data flow]
+```
+
+#### Interface Design
+
+| Interface | Input | Output | Description |
+|-----------|-------|--------|-------------|
+| [Interface1] | [Input] | [Output] | [Description] |
+
+---
+
+### Acceptance Criteria
+
+#### AC-001: [Acceptance Criteria Title]
+
+**Description**: [One-sentence description]
+
+**Acceptance conditions**:
+- [ ] [Condition 1]
+- [ ] [Condition 2]
+
+**Testing approach**: [Explain how to test]
+
+---
+
+### Documentation Impact
+
+#### Documents to Update
+
+| Document | Update Reason | Priority |
+|----------|---------------|----------|
+| [Document1] | [Reason] | P0 |
+
+#### Documents Not Requiring Updates
+
+- [ ] This change is an internal refactoring and doesn't affect user-visible functionality
+- [ ] This change only fixes bugs and doesn't introduce new features
+
+---
+
+### Architecture Impact
+
+#### New Dependencies
+
+| Dependency | Version | Purpose | Risk |
+|------------|---------|---------|------|
+| [Dependency1] | [Version] | [Purpose] | [Risk] |
+
+#### Modified Modules
+
+| Module | Modification Type | Impact Scope |
+|--------|-------------------|--------------|
+| [Module1] | [Add/Modify/Delete] | [Impact scope] |
+
+---
+
+## Approval History
+
+| Time | Phase | Action | Actor | Reason |
+|------|-------|--------|-------|--------|
+| [Time] | Design | Created | AI | - |
+| [Time] | Design | Approved | User | [Reason] |
+```
+
+## Usage Guide
+
+### 1. Purpose of Bottom Line Up Front
+
+- **30-second quick understanding**: Let users immediately know the core content of the design
+- **Comparison with Proposal**: Clearly explain the difference between design and proposal
+- **Reduce cognitive load**: Use plain language, avoid technical jargon
+
+### 2. Purpose of Requirements Alignment Check
+
+- **Lightweight alignment**: Only requires user confirmation when new issues or constraints are discovered
+- **Quick decision**: In most cases, users only need to confirm "agree" or "disagree"
+- **Retain control**: Users can reject adjustments at any time
+
+### 3. Purpose of Detailed Design
+
+- **AI reading**: Provides complete technical details for AI reference
+- **Humans can skip**: Humans only need to read "Bottom Line Up Front" and "Requirements Alignment Check" sections
+
+### 4. Purpose of Acceptance Criteria
+
+- **Testable**: Each acceptance criterion should be testable
+- **Traceable**: Acceptance criteria should correspond to Proposal objectives
+- **Verifiable**: Acceptance criteria should clearly explain how to verify