dev-playbooks 1.5.2 → 1.5.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dev-playbooks",
-  "version": "1.5.2",
+  "version": "1.5.4",
   "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`

package/skills/devbooks-test-reviewer/SKILL.md

@@ -53,6 +53,34 @@ Before execution, you **must** search for configuration in the following order (
 - Must compare against `verification.md` to check if tests cover all ACs
 - If missing tests are found, clearly indicate the missing AC-ID
 
+### CON-ROLE-004: Only Review Test Code Quality, Not Runtime Results
+> Core principle: Test Reviewer focuses on "**how well tests are written**", not "**whether tests pass**"
+
+**Prohibited**:
+- Discussing whether tests Pass/Fail, Red/Green, or Skip
+- Commenting on "functionality not implemented" or "missing dependencies"
+- Providing implementation suggestions to Coder (e.g., "implement xxx command", "add xxx field")
+- Referencing workflow phases (e.g., "Red baseline phase", "this is expected behavior")
+- Judging test quality based on test runtime results
+
+**Allowed**:
+- Reviewing correctness and clarity of test assertions
+- Reviewing test structure and organization
+- Reviewing completeness of test scenarios (based on code analysis, not runtime results)
+
+### CON-ROLE-005: Coverage = Test Existence, Not Test Pass Status
+
+| Coverage Status | Definition | Judgment Criteria |
+|-----------------|------------|-------------------|
+| ✅ Covered | Corresponding test case exists for AC | Test/it block exists in test file |
+| ⚠️ Partially Covered | Test exists but scenarios incomplete | Missing boundary conditions, error paths, etc. |
+| ❌ Missing | No corresponding test case | No matching test code found |
+
+**Prohibited** from including the following in coverage assessment:
+- Test Skip status (skipped tests still count as "Covered")
+- Test Fail status (failing tests still count as "Covered")
+- Test runtime or performance
+
 ---
 
 ## Review Dimensions
@@ -104,11 +132,13 @@ Before execution, you **must** search for configuration in the following order (
 
 ## Coverage Analysis
 
+> **Note**: Coverage status is based on test code existence, not test runtime results (Pass/Fail/Skip).
+
 | AC-ID | Test File | Coverage Status | Notes |
 |-------|-----------|-----------------|-------|
-| AC-001 | test-a.ts | Covered | - |
-| AC-002 | - | Missing | Needs to be added |
-| AC-003 | test-b.ts | Partially Covered | Missing boundary conditions |
+| AC-001 | test-a.ts | ✅ Covered | Test case exists |
+| AC-002 | - | ❌ Missing | No corresponding test code |
+| AC-003 | test-b.ts | ⚠️ Partially Covered | Test exists but missing boundary conditions |
 
 ## Issue List
 
@@ -178,7 +208,7 @@ After completing the review, you **must** provide a clear conclusion:
 | Skill Name | devbooks-test-reviewer |
 | Phase | Apply |
 | Artifact | Review report (not written to change package) |
-| Constraints | CON-ROLE-001~003 |
+| Constraints | CON-ROLE-001~005 |
 
 ---