dev-playbooks 1.5.3 → 1.5.5

package/README.md

@@ -196,7 +196,6 @@ Run devbooks-archiver skill for change add-oauth2
 | Skill | Description |
 |-------|-------------|
 | devbooks-archiver | Maintain/dedupe specs |
-| devbooks-delivery-workflow | End-to-end delivery workflow |
 
 ### Standalone Skills
 
@@ -206,6 +205,14 @@ Run devbooks-archiver skill for change add-oauth2
 | devbooks-brownfield-bootstrap | Brownfield project bootstrap |
 | devbooks-convergence-audit | Convergence audit (anti-deception design) |
 
+### Orchestration Layer (For tools with sub-agent support)
+
+| Skill | Description |
+|-------|-------------|
+| devbooks-delivery-workflow | Complete closed-loop orchestrator, auto-orchestrates Proposal→Design→Spec→Plan→Test→Code→Review→Archive workflow |
+
+> **Note**: `devbooks-delivery-workflow` is an orchestration layer Skill, designed for AI programming tools with sub-agent support (e.g., Claude Code with Task tool). It calls sub-agents to execute each stage's Skill, completing the full change closed-loop.
+
 ---
 
 ## DevBooks Comparisons

package/bin/devbooks.js

@@ -5,17 +5,17 @@
  *
  * AI-agnostic spec-driven development workflow
  *
- * 用法：
- *   dev-playbooks-cn init [path] [options]
- *   dev-playbooks-cn update [path]
- *   dev-playbooks-cn migrate --from <framework> [options]
+ * Usage:
+ *   dev-playbooks init [path] [options]
+ *   dev-playbooks update [path]           # Update CLI and configured tools
+ *   dev-playbooks migrate --from <framework> [options]
  *
- * 选项：
- *   --tools <tools>    非交互式指定 AI 工具：all, none, 或逗号分隔的列表
- *   --from <framework> 迁移来源框架：openspec, speckit
- *   --dry-run          模拟运行，不实际修改文件
- *   --keep-old         迁移后保留原目录
- *   --help             显示帮助信息
+ * Options:
+ *   --tools <tools>    Non-interactive tool selection: all, none, or comma-separated list
+ *   --from <framework> Migration source: openspec, speckit
+ *   --dry-run          Dry run, don't modify files
+ *   --keep-old         Keep old directory after migration
+ *   --help             Show help
  *   --version          Show version
  */
 
@@ -316,6 +316,70 @@ function getCliVersion() {
   }
 }
 
+/**
+ * Check if a new version is available on npm
+ * @returns {Promise<{hasUpdate: boolean, latestVersion: string|null, currentVersion: string}>}
+ */
+async function checkNpmUpdate() {
+  const currentVersion = getCliVersion();
+  try {
+    const { execSync } = await import('child_process');
+    const latestVersion = execSync(`npm view ${CLI_COMMAND} version`, {
+      encoding: 'utf-8',
+      timeout: 10000,
+      stdio: ['pipe', 'pipe', 'pipe']
+    }).trim();
+
+    if (latestVersion && latestVersion !== currentVersion) {
+      // Simple semver comparison
+      const current = currentVersion.split('.').map(Number);
+      const latest = latestVersion.split('.').map(Number);
+      const hasUpdate = latest[0] > current[0] ||
+        (latest[0] === current[0] && latest[1] > current[1]) ||
+        (latest[0] === current[0] && latest[1] === current[1] && latest[2] > current[2]);
+      return { hasUpdate, latestVersion, currentVersion };
+    }
+    return { hasUpdate: false, latestVersion, currentVersion };
+  } catch {
+    // Network error or timeout, silently ignore
+    return { hasUpdate: false, latestVersion: null, currentVersion };
+  }
+}
+
+/**
+ * Perform npm global update
+ * @returns {Promise<boolean>} Whether the update succeeded
+ */
+async function performNpmUpdate() {
+  return new Promise((resolve) => {
+    const spinner = ora(`Updating ${CLI_COMMAND}...`).start();
+    const child = spawn('npm', ['install', '-g', CLI_COMMAND], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      shell: true
+    });
+
+    let stderr = '';
+    child.stderr.on('data', (data) => {
+      stderr += data.toString();
+    });
+
+    child.on('close', (code) => {
+      if (code === 0) {
+        spinner.succeed(`${CLI_COMMAND} updated to latest version`);
+        resolve(true);
+      } else {
+        spinner.fail(`Update failed: ${stderr || 'Unknown error'}`);
+        resolve(false);
+      }
+    });
+
+    child.on('error', (err) => {
+      spinner.fail(`Update failed: ${err.message}`);
+      resolve(false);
+    });
+  });
+}
+
 // ============================================================================
 // Auto-update .gitignore and .npmignore
 // ============================================================================
@@ -1297,7 +1361,32 @@ async function updateCommand(projectDir) {
   console.log(chalk.bold('DevBooks Update'));
   console.log();
 
-  // Check if initialized
+  // 1. Check if CLI has a new version
+  const spinner = ora('Checking for CLI updates...').start();
+  const { hasUpdate, latestVersion, currentVersion } = await checkNpmUpdate();
+
+  if (hasUpdate) {
+    spinner.info(`New version available: ${currentVersion} → ${latestVersion}`);
+    const shouldUpdate = await confirm({
+      message: `Update ${CLI_COMMAND} to ${latestVersion}?`,
+      default: true
+    });
+
+    if (shouldUpdate) {
+      const success = await performNpmUpdate();
+      if (success) {
+        console.log(chalk.blue('ℹ') + ` Please run \`${CLI_COMMAND} update\` again to update project files.`);
+        return;
+      }
+      // Update failed, continue with local file updates
+    }
+  } else {
+    spinner.succeed(`CLI is up to date (v${currentVersion})`);
+  }
+
+  console.log();
+
+  // 2. Check if initialized (update project files)
   const configPath = path.join(projectDir, '.devbooks', 'config.yaml');
   if (!fs.existsSync(configPath)) {
     console.log(chalk.red('✗') + ` DevBooks config not found. Please run \`${CLI_COMMAND} init\` first.`);
@@ -1464,7 +1553,7 @@ function showHelp() {
   console.log();
   console.log(chalk.cyan('Usage:'));
   console.log(`  ${CLI_COMMAND} init [path] [options]              Initialize DevBooks`);
-  console.log(`  ${CLI_COMMAND} update [path]                      Update configured tools`);
+  console.log(`  ${CLI_COMMAND} update [path]                      Update CLI and configured tools`);
   console.log(`  ${CLI_COMMAND} migrate --from <framework> [opts]  Migrate from other frameworks`);
   console.log();
   console.log(chalk.cyan('Options:'));
@@ -1518,7 +1607,7 @@ function showHelp() {
   console.log(`  ${CLI_COMMAND} init my-project             # Initialize in my-project directory`);
   console.log(`  ${CLI_COMMAND} init --tools claude,cursor  # Non-interactive (project-level by default)`);
   console.log(`  ${CLI_COMMAND} init --tools claude --scope global  # Non-interactive (global installation)`);
-  console.log(`  ${CLI_COMMAND} update                      # Update configured tools`);
+  console.log(`  ${CLI_COMMAND} update                      # Update CLI and Skills`);
   console.log(`  ${CLI_COMMAND} migrate --from openspec     # Migrate from OpenSpec`);
   console.log(`  ${CLI_COMMAND} migrate --from speckit      # Migrate from spec-kit`);
   console.log(`  ${CLI_COMMAND} migrate --from openspec --dry-run  # Dry run migration`);

package/package.json

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

package/skills/devbooks-delivery-workflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: devbooks-delivery-workflow
-description: devbooks-delivery-workflow: Run a change through a traceable closed-loop workflow (Design->Plan->Trace->Verify->Implement->Archive), with clear DoD, traceability matrix, and role isolation (Test Owner and Coder separation). Use when the user says "run closed-loop/delivery acceptance/traceability matrix/DoD/close and archive/acceptance workflow" etc.
+description: "devbooks-delivery-workflow: Complete closed-loop orchestrator that runs in AI programming tools with sub-agent support, automatically orchestrating the full Proposal→Design→Spec→Plan→Test→Implement→Review→Archive workflow. Use when the user says 'run closed-loop/complete delivery/end-to-end flow/automated change workflow' etc."
 allowed-tools:
   - Glob
   - Grep
@@ -8,9 +8,12 @@ allowed-tools:
   - Write
   - Edit
   - Bash
+  - Task
 ---
 
-# DevBooks: Delivery Acceptance Workflow (Closed-Loop Skeleton)
+# DevBooks: Delivery Acceptance Workflow (Complete Closed-Loop Orchestrator)
+
+> **Positioning**: This Skill is an **orchestration layer**, not a daily-use Skill. It runs in AI programming tools with sub-agent support (e.g., Claude Code with Task tool) to automatically orchestrate complete change closed-loops.
 
 ## Prerequisites: Configuration Discovery (Protocol-Agnostic)
 
@@ -28,57 +31,83 @@ Before execution, **must** search for configuration in the following order (stop
 - Do not guess directory roots
 - Do not skip reading the rules document
 
-## Change Package Naming Convention (Mandatory)
+## Core Responsibility: Complete Closed-Loop Orchestration
 
-Change package ID (change-id) **must** follow this naming convention:
+This Skill's core capability is **orchestrating sub-agents to complete the full change closed-loop**.
 
-### Format
+### Closed-Loop Flow (8 Stages)
 
 ```
-<datetime>-<verb-prefixed-semantic-description>
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│  1. Propose │ ──▶ │  2. Design  │ ──▶ │  3. Spec    │ ──▶ │  4. Plan    │
+└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
+       │                                                           │
+       ▼                                                           ▼
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│  8. Archive │ ◀── │  7. Review  │ ◀── │  6. Code    │ ◀── │  5. Test    │
+└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
 ```
 
-### Rules
+### Stage Details and Corresponding Skills
 
-| Component | Rule | Example |
-|-----------|------|---------|
-| Datetime | `YYYYMMDD-HHMM` format | `20240116-1030` |
-| Separator | Use `-` between datetime and semantic | `-` |
-| Semantic description | **Must start with a verb**, use lowercase and hyphens | `add-oauth2`, `fix-login-bug` |
+| Stage | Skill | Artifact | Role |
+|-------|-------|----------|------|
+| 1. Propose | `devbooks-proposal-author` | proposal.md | Author |
+| 1.5 Challenge (optional) | `devbooks-proposal-challenger` | Challenge comments | Challenger |
+| 1.6 Judge (optional) | `devbooks-proposal-judge` | Decision | Judge |
+| 2. Design | `devbooks-design-doc` | design.md | Designer |
+| 3. Spec | `devbooks-spec-contract` | specs/*.md | Spec Owner |
+| 4. Plan | `devbooks-implementation-plan` | tasks.md | Planner |
+| 5. Test | `devbooks-test-owner` | verification.md + tests/ | Test Owner |
+| 6. Code | `devbooks-coder` | src/ implementation | Coder |
+| 7. Review | `devbooks-code-review` | Review comments | Reviewer |
+| 7.5 Test Review (optional) | `devbooks-test-reviewer` | Test review | Test Reviewer |
+| 8. Archive | `devbooks-archiver` | Archived to truth source | Archiver |
 
-### Valid Examples
+### Orchestration Logic
 
-```bash
-# ✅ Correct
-20240116-1030-add-oauth2-support
-20240116-1430-fix-user-auth-bug
-20240116-0900-refactor-payment-module
-20240115-2200-update-api-docs
-
-# ❌ Incorrect
-add-oauth2                    # Missing datetime
-20240116-oauth2               # Semantic doesn't start with verb
-2024-01-16-add-oauth2         # Wrong date format (shouldn't have -)
-oauth2-20240116               # Wrong order
 ```
+1. Receive user requirement
+2. Call proposal-author to create proposal (auto-generate change-id)
+3. [Optional] Call proposal-challenger to challenge proposal
+4. [Optional] Call proposal-judge to adjudicate
+5. Call design-doc to create design document
+6. [If external contracts] Call spec-contract to define specs
+7. Call implementation-plan to create implementation plan
+8. Call test-owner to write tests (independent Agent)
+9. Call coder to implement features (independent Agent)
+10. Call code-review to review code
+11. [Optional] Call test-reviewer to review tests
+12. Call archiver to archive to truth source
+```
+
+### Role Isolation Constraints
+
+**Key Principle**: Test Owner and Coder must use **independent Agent instances/sessions**.
 
-### Common Verbs
+| Role | Isolation Requirement | Reason |
+|------|----------------------|--------|
+| Test Owner | Independent Agent | Prevent Coder from tampering with tests |
+| Coder | Independent Agent | Prevent Coder from seeing test implementation details |
+| Reviewer | Independent Agent (recommended) | Maintain review objectivity |
 
-| Verb | Usage |
-|------|-------|
-| `add` | Add new feature |
-| `fix` | Fix defect |
-| `update` | Update existing feature |
-| `refactor` | Refactor code |
-| `remove` | Remove feature |
-| `improve` | Improve performance/experience |
-| `migrate` | Migrate data/system |
+### Gate Checkpoints
 
-### Why This Naming Convention?
+After each stage completes, call `change-check.sh` to verify:
 
-1. **Timestamp first**: Auto-sorts by time in archive directory
-2. **Verb prefix**: Clearly expresses change intent, aids code review
-3. **Lowercase hyphens**: Avoids cross-platform filename issues
+```bash
+# Proposal stage check
+change-check.sh <change-id> --mode proposal
+
+# Implementation stage check (Test Owner)
+change-check.sh <change-id> --mode apply --role test-owner
+
+# Implementation stage check (Coder)
+change-check.sh <change-id> --mode apply --role coder
+
+# Pre-archive check
+change-check.sh <change-id> --mode archive
+```
 
 ## Reference Skeleton (Read as Needed)
 

package/skills/devbooks-delivery-workflow/scripts/change-scaffold.sh

@@ -81,6 +81,82 @@ if [[ -z "$change_id" || "$change_id" == "-"* || "$change_id" =~ [[:space:]] ]];
   exit 2
 fi
 
+# Validate change-id format: YYYYMMDD-HHMM-<verb-prefixed-description>
+# Format: datetime-verb-prefixed-semantic-description
+# Example: 20240116-1030-add-oauth2-support
+validate_change_id_format() {
+  local id="$1"
+
+  # Pattern: 8 digits (date) + hyphen + 4 digits (time) + hyphen + verb-prefixed-description
+  # Date: YYYYMMDD, Time: HHMM
+  if [[ ! "$id" =~ ^[0-9]{8}-[0-9]{4}-.+ ]]; then
+    return 1
+  fi
+
+  # Extract datetime part for validation
+  local date_part="${id:0:8}"
+  local time_part="${id:9:4}"
+  local desc_part="${id:14}"
+
+  # Validate date (basic check: year 2020-2099, month 01-12, day 01-31)
+  local year="${date_part:0:4}"
+  local month="${date_part:4:2}"
+  local day="${date_part:6:2}"
+
+  # Remove leading zeros for numeric comparison
+  year=$((10#$year))
+  month=$((10#$month))
+  day=$((10#$day))
+
+  if [[ "$year" -lt 2020 || "$year" -gt 2099 ]]; then
+    return 1
+  fi
+  if [[ "$month" -lt 1 || "$month" -gt 12 ]]; then
+    return 1
+  fi
+  if [[ "$day" -lt 1 || "$day" -gt 31 ]]; then
+    return 1
+  fi
+
+  # Validate time (hour 00-23, minute 00-59)
+  local hour="${time_part:0:2}"
+  local minute="${time_part:2:2}"
+
+  hour=$((10#$hour))
+  minute=$((10#$minute))
+
+  if [[ "$hour" -lt 0 || "$hour" -gt 23 ]]; then
+    return 1
+  fi
+  if [[ "$minute" -lt 0 || "$minute" -gt 59 ]]; then
+    return 1
+  fi
+
+  # Validate description starts with a verb (common verbs)
+  local verb_pattern="^(add|fix|update|refactor|remove|improve|migrate|implement|enable|disable|change|create|delete|modify|optimize|resolve|setup|init|configure|introduce|extract|merge|split|move|rename|deprecate|upgrade|downgrade|revert|sync|integrate|unify|standardize|simplify|extend|reduce|enhance|support|handle|validate|test|document|cleanup|prepare|finalize|complete|release|publish|deploy|hotfix|patch|bump)-"
+
+  if [[ ! "$desc_part" =~ $verb_pattern ]]; then
+    return 1
+  fi
+
+  return 0
+}
+
+if ! validate_change_id_format "$change_id"; then
+  echo "error: invalid change-id format: '$change_id'" >&2
+  echo "" >&2
+  echo "Expected format: YYYYMMDD-HHMM-<verb-prefixed-description>" >&2
+  echo "Example: 20240116-1030-add-oauth2-support" >&2
+  echo "" >&2
+  echo "Rules:" >&2
+  echo "  - Date: YYYYMMDD (e.g., 20240116)" >&2
+  echo "  - Time: HHMM (e.g., 1030 for 10:30)" >&2
+  echo "  - Description: must start with a verb (add/fix/update/refactor/...)" >&2
+  echo "" >&2
+  echo "Common verbs: add, fix, update, refactor, remove, improve, migrate, implement" >&2
+  exit 2
+fi
+
 if [[ -z "$project_root" || -z "$change_root" || -z "$truth_root" ]]; then
   usage
   exit 2

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

@@ -32,6 +32,66 @@ Before execution, you **must** search for configuration in the following order (
 1. **Proposal Authoring**: Produce clear, reviewable, and actionable change proposals
 2. **Design Decision Interaction**: For design choices that cannot be objectively judged as better or worse (where A and B are both viable depending on preferences), present options to users for their decision rather than deciding unilaterally
 
+## Change Package Naming Convention (Mandatory)
+
+Change package ID (change-id) **must** follow this naming convention:
+
+### Format
+
+```
+<datetime>-<verb-prefixed-semantic-description>
+```
+
+### Rules
+
+| Component | Rule | Example |
+|-----------|------|---------|
+| Datetime | `YYYYMMDD-HHMM` format | `20240116-1030` |
+| Separator | Use `-` between datetime and semantic | `-` |
+| Semantic description | **Must start with a verb**, use lowercase and hyphens | `add-oauth2`, `fix-login-bug` |
+
+### Examples
+
+```bash
+# ✅ Correct
+20240116-1030-add-oauth2-support
+20240116-1430-fix-user-auth-bug
+20240116-0900-refactor-payment-module
+20240115-2200-update-api-docs
+
+# ❌ Incorrect
+add-oauth2                    # Missing datetime
+20240116-oauth2               # Semantic doesn't start with verb
+2024-01-16-add-oauth2         # Wrong date format (shouldn't have -)
+oauth2-20240116               # Wrong order
+```
+
+### Common Verbs
+
+| Verb | Usage |
+|------|-------|
+| `add` | Add new feature |
+| `fix` | Fix defect |
+| `update` | Update existing feature |
+| `refactor` | Refactor code |
+| `remove` | Remove feature |
+| `improve` | Improve performance/experience |
+| `migrate` | Migrate data/system |
+
+### Why This Naming Convention?
+
+1. **Timestamp first**: Auto-sorts by time in archive directory
+2. **Verb prefix**: Clearly expresses change intent, aids code review
+3. **Lowercase hyphens**: Avoids cross-platform filename issues
+
+### Creating Change Package
+
+After determining the change-id, call the scaffold script to initialize the change package:
+
+```bash
+change-scaffold.sh <change-id> --project-root <repo-root> --change-root <change-root> --truth-root <truth-root>
+```
+
 ## Artifact Location
 
 - Proposal: `<change-root>/<change-id>/proposal.md`