dev-playbooks 1.5.3 → 1.5.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: devbooks-delivery-workflow
|
|
3
|
-
description: devbooks-delivery-workflow:
|
|
3
|
+
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."
|
|
4
4
|
allowed-tools:
|
|
5
5
|
- Glob
|
|
6
6
|
- Grep
|
|
@@ -8,9 +8,12 @@ allowed-tools:
|
|
|
8
8
|
- Write
|
|
9
9
|
- Edit
|
|
10
10
|
- Bash
|
|
11
|
+
- Task
|
|
11
12
|
---
|
|
12
13
|
|
|
13
|
-
# DevBooks: Delivery Acceptance Workflow (Closed-Loop
|
|
14
|
+
# DevBooks: Delivery Acceptance Workflow (Complete Closed-Loop Orchestrator)
|
|
15
|
+
|
|
16
|
+
> **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.
|
|
14
17
|
|
|
15
18
|
## Prerequisites: Configuration Discovery (Protocol-Agnostic)
|
|
16
19
|
|
|
@@ -28,57 +31,83 @@ Before execution, **must** search for configuration in the following order (stop
|
|
|
28
31
|
- Do not guess directory roots
|
|
29
32
|
- Do not skip reading the rules document
|
|
30
33
|
|
|
31
|
-
##
|
|
34
|
+
## Core Responsibility: Complete Closed-Loop Orchestration
|
|
32
35
|
|
|
33
|
-
|
|
36
|
+
This Skill's core capability is **orchestrating sub-agents to complete the full change closed-loop**.
|
|
34
37
|
|
|
35
|
-
###
|
|
38
|
+
### Closed-Loop Flow (8 Stages)
|
|
36
39
|
|
|
37
40
|
```
|
|
38
|
-
|
|
41
|
+
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
|
42
|
+
│ 1. Propose │ ──▶ │ 2. Design │ ──▶ │ 3. Spec │ ──▶ │ 4. Plan │
|
|
43
|
+
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
|
|
44
|
+
│ │
|
|
45
|
+
▼ ▼
|
|
46
|
+
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
|
47
|
+
│ 8. Archive │ ◀── │ 7. Review │ ◀── │ 6. Code │ ◀── │ 5. Test │
|
|
48
|
+
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
|
|
39
49
|
```
|
|
40
50
|
|
|
41
|
-
###
|
|
51
|
+
### Stage Details and Corresponding Skills
|
|
42
52
|
|
|
43
|
-
|
|
|
44
|
-
|
|
45
|
-
|
|
|
46
|
-
|
|
|
47
|
-
|
|
|
53
|
+
| Stage | Skill | Artifact | Role |
|
|
54
|
+
|-------|-------|----------|------|
|
|
55
|
+
| 1. Propose | `devbooks-proposal-author` | proposal.md | Author |
|
|
56
|
+
| 1.5 Challenge (optional) | `devbooks-proposal-challenger` | Challenge comments | Challenger |
|
|
57
|
+
| 1.6 Judge (optional) | `devbooks-proposal-judge` | Decision | Judge |
|
|
58
|
+
| 2. Design | `devbooks-design-doc` | design.md | Designer |
|
|
59
|
+
| 3. Spec | `devbooks-spec-contract` | specs/*.md | Spec Owner |
|
|
60
|
+
| 4. Plan | `devbooks-implementation-plan` | tasks.md | Planner |
|
|
61
|
+
| 5. Test | `devbooks-test-owner` | verification.md + tests/ | Test Owner |
|
|
62
|
+
| 6. Code | `devbooks-coder` | src/ implementation | Coder |
|
|
63
|
+
| 7. Review | `devbooks-code-review` | Review comments | Reviewer |
|
|
64
|
+
| 7.5 Test Review (optional) | `devbooks-test-reviewer` | Test review | Test Reviewer |
|
|
65
|
+
| 8. Archive | `devbooks-archiver` | Archived to truth source | Archiver |
|
|
48
66
|
|
|
49
|
-
###
|
|
67
|
+
### Orchestration Logic
|
|
50
68
|
|
|
51
|
-
```bash
|
|
52
|
-
# ✅ Correct
|
|
53
|
-
20240116-1030-add-oauth2-support
|
|
54
|
-
20240116-1430-fix-user-auth-bug
|
|
55
|
-
20240116-0900-refactor-payment-module
|
|
56
|
-
20240115-2200-update-api-docs
|
|
57
|
-
|
|
58
|
-
# ❌ Incorrect
|
|
59
|
-
add-oauth2 # Missing datetime
|
|
60
|
-
20240116-oauth2 # Semantic doesn't start with verb
|
|
61
|
-
2024-01-16-add-oauth2 # Wrong date format (shouldn't have -)
|
|
62
|
-
oauth2-20240116 # Wrong order
|
|
63
69
|
```
|
|
70
|
+
1. Receive user requirement
|
|
71
|
+
2. Call proposal-author to create proposal (auto-generate change-id)
|
|
72
|
+
3. [Optional] Call proposal-challenger to challenge proposal
|
|
73
|
+
4. [Optional] Call proposal-judge to adjudicate
|
|
74
|
+
5. Call design-doc to create design document
|
|
75
|
+
6. [If external contracts] Call spec-contract to define specs
|
|
76
|
+
7. Call implementation-plan to create implementation plan
|
|
77
|
+
8. Call test-owner to write tests (independent Agent)
|
|
78
|
+
9. Call coder to implement features (independent Agent)
|
|
79
|
+
10. Call code-review to review code
|
|
80
|
+
11. [Optional] Call test-reviewer to review tests
|
|
81
|
+
12. Call archiver to archive to truth source
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
### Role Isolation Constraints
|
|
85
|
+
|
|
86
|
+
**Key Principle**: Test Owner and Coder must use **independent Agent instances/sessions**.
|
|
64
87
|
|
|
65
|
-
|
|
88
|
+
| Role | Isolation Requirement | Reason |
|
|
89
|
+
|------|----------------------|--------|
|
|
90
|
+
| Test Owner | Independent Agent | Prevent Coder from tampering with tests |
|
|
91
|
+
| Coder | Independent Agent | Prevent Coder from seeing test implementation details |
|
|
92
|
+
| Reviewer | Independent Agent (recommended) | Maintain review objectivity |
|
|
66
93
|
|
|
67
|
-
|
|
68
|
-
|------|-------|
|
|
69
|
-
| `add` | Add new feature |
|
|
70
|
-
| `fix` | Fix defect |
|
|
71
|
-
| `update` | Update existing feature |
|
|
72
|
-
| `refactor` | Refactor code |
|
|
73
|
-
| `remove` | Remove feature |
|
|
74
|
-
| `improve` | Improve performance/experience |
|
|
75
|
-
| `migrate` | Migrate data/system |
|
|
94
|
+
### Gate Checkpoints
|
|
76
95
|
|
|
77
|
-
|
|
96
|
+
After each stage completes, call `change-check.sh` to verify:
|
|
78
97
|
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
98
|
+
```bash
|
|
99
|
+
# Proposal stage check
|
|
100
|
+
change-check.sh <change-id> --mode proposal
|
|
101
|
+
|
|
102
|
+
# Implementation stage check (Test Owner)
|
|
103
|
+
change-check.sh <change-id> --mode apply --role test-owner
|
|
104
|
+
|
|
105
|
+
# Implementation stage check (Coder)
|
|
106
|
+
change-check.sh <change-id> --mode apply --role coder
|
|
107
|
+
|
|
108
|
+
# Pre-archive check
|
|
109
|
+
change-check.sh <change-id> --mode archive
|
|
110
|
+
```
|
|
82
111
|
|
|
83
112
|
## Reference Skeleton (Read as Needed)
|
|
84
113
|
|
|
@@ -81,6 +81,82 @@ if [[ -z "$change_id" || "$change_id" == "-"* || "$change_id" =~ [[:space:]] ]];
|
|
|
81
81
|
exit 2
|
|
82
82
|
fi
|
|
83
83
|
|
|
84
|
+
# Validate change-id format: YYYYMMDD-HHMM-<verb-prefixed-description>
|
|
85
|
+
# Format: datetime-verb-prefixed-semantic-description
|
|
86
|
+
# Example: 20240116-1030-add-oauth2-support
|
|
87
|
+
validate_change_id_format() {
|
|
88
|
+
local id="$1"
|
|
89
|
+
|
|
90
|
+
# Pattern: 8 digits (date) + hyphen + 4 digits (time) + hyphen + verb-prefixed-description
|
|
91
|
+
# Date: YYYYMMDD, Time: HHMM
|
|
92
|
+
if [[ ! "$id" =~ ^[0-9]{8}-[0-9]{4}-.+ ]]; then
|
|
93
|
+
return 1
|
|
94
|
+
fi
|
|
95
|
+
|
|
96
|
+
# Extract datetime part for validation
|
|
97
|
+
local date_part="${id:0:8}"
|
|
98
|
+
local time_part="${id:9:4}"
|
|
99
|
+
local desc_part="${id:14}"
|
|
100
|
+
|
|
101
|
+
# Validate date (basic check: year 2020-2099, month 01-12, day 01-31)
|
|
102
|
+
local year="${date_part:0:4}"
|
|
103
|
+
local month="${date_part:4:2}"
|
|
104
|
+
local day="${date_part:6:2}"
|
|
105
|
+
|
|
106
|
+
# Remove leading zeros for numeric comparison
|
|
107
|
+
year=$((10#$year))
|
|
108
|
+
month=$((10#$month))
|
|
109
|
+
day=$((10#$day))
|
|
110
|
+
|
|
111
|
+
if [[ "$year" -lt 2020 || "$year" -gt 2099 ]]; then
|
|
112
|
+
return 1
|
|
113
|
+
fi
|
|
114
|
+
if [[ "$month" -lt 1 || "$month" -gt 12 ]]; then
|
|
115
|
+
return 1
|
|
116
|
+
fi
|
|
117
|
+
if [[ "$day" -lt 1 || "$day" -gt 31 ]]; then
|
|
118
|
+
return 1
|
|
119
|
+
fi
|
|
120
|
+
|
|
121
|
+
# Validate time (hour 00-23, minute 00-59)
|
|
122
|
+
local hour="${time_part:0:2}"
|
|
123
|
+
local minute="${time_part:2:2}"
|
|
124
|
+
|
|
125
|
+
hour=$((10#$hour))
|
|
126
|
+
minute=$((10#$minute))
|
|
127
|
+
|
|
128
|
+
if [[ "$hour" -lt 0 || "$hour" -gt 23 ]]; then
|
|
129
|
+
return 1
|
|
130
|
+
fi
|
|
131
|
+
if [[ "$minute" -lt 0 || "$minute" -gt 59 ]]; then
|
|
132
|
+
return 1
|
|
133
|
+
fi
|
|
134
|
+
|
|
135
|
+
# Validate description starts with a verb (common verbs)
|
|
136
|
+
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)-"
|
|
137
|
+
|
|
138
|
+
if [[ ! "$desc_part" =~ $verb_pattern ]]; then
|
|
139
|
+
return 1
|
|
140
|
+
fi
|
|
141
|
+
|
|
142
|
+
return 0
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
if ! validate_change_id_format "$change_id"; then
|
|
146
|
+
echo "error: invalid change-id format: '$change_id'" >&2
|
|
147
|
+
echo "" >&2
|
|
148
|
+
echo "Expected format: YYYYMMDD-HHMM-<verb-prefixed-description>" >&2
|
|
149
|
+
echo "Example: 20240116-1030-add-oauth2-support" >&2
|
|
150
|
+
echo "" >&2
|
|
151
|
+
echo "Rules:" >&2
|
|
152
|
+
echo " - Date: YYYYMMDD (e.g., 20240116)" >&2
|
|
153
|
+
echo " - Time: HHMM (e.g., 1030 for 10:30)" >&2
|
|
154
|
+
echo " - Description: must start with a verb (add/fix/update/refactor/...)" >&2
|
|
155
|
+
echo "" >&2
|
|
156
|
+
echo "Common verbs: add, fix, update, refactor, remove, improve, migrate, implement" >&2
|
|
157
|
+
exit 2
|
|
158
|
+
fi
|
|
159
|
+
|
|
84
160
|
if [[ -z "$project_root" || -z "$change_root" || -z "$truth_root" ]]; then
|
|
85
161
|
usage
|
|
86
162
|
exit 2
|
|
@@ -32,6 +32,66 @@ Before execution, you **must** search for configuration in the following order (
|
|
|
32
32
|
1. **Proposal Authoring**: Produce clear, reviewable, and actionable change proposals
|
|
33
33
|
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
|
|
34
34
|
|
|
35
|
+
## Change Package Naming Convention (Mandatory)
|
|
36
|
+
|
|
37
|
+
Change package ID (change-id) **must** follow this naming convention:
|
|
38
|
+
|
|
39
|
+
### Format
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
<datetime>-<verb-prefixed-semantic-description>
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
### Rules
|
|
46
|
+
|
|
47
|
+
| Component | Rule | Example |
|
|
48
|
+
|-----------|------|---------|
|
|
49
|
+
| Datetime | `YYYYMMDD-HHMM` format | `20240116-1030` |
|
|
50
|
+
| Separator | Use `-` between datetime and semantic | `-` |
|
|
51
|
+
| Semantic description | **Must start with a verb**, use lowercase and hyphens | `add-oauth2`, `fix-login-bug` |
|
|
52
|
+
|
|
53
|
+
### Examples
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
# ✅ Correct
|
|
57
|
+
20240116-1030-add-oauth2-support
|
|
58
|
+
20240116-1430-fix-user-auth-bug
|
|
59
|
+
20240116-0900-refactor-payment-module
|
|
60
|
+
20240115-2200-update-api-docs
|
|
61
|
+
|
|
62
|
+
# ❌ Incorrect
|
|
63
|
+
add-oauth2 # Missing datetime
|
|
64
|
+
20240116-oauth2 # Semantic doesn't start with verb
|
|
65
|
+
2024-01-16-add-oauth2 # Wrong date format (shouldn't have -)
|
|
66
|
+
oauth2-20240116 # Wrong order
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
### Common Verbs
|
|
70
|
+
|
|
71
|
+
| Verb | Usage |
|
|
72
|
+
|------|-------|
|
|
73
|
+
| `add` | Add new feature |
|
|
74
|
+
| `fix` | Fix defect |
|
|
75
|
+
| `update` | Update existing feature |
|
|
76
|
+
| `refactor` | Refactor code |
|
|
77
|
+
| `remove` | Remove feature |
|
|
78
|
+
| `improve` | Improve performance/experience |
|
|
79
|
+
| `migrate` | Migrate data/system |
|
|
80
|
+
|
|
81
|
+
### Why This Naming Convention?
|
|
82
|
+
|
|
83
|
+
1. **Timestamp first**: Auto-sorts by time in archive directory
|
|
84
|
+
2. **Verb prefix**: Clearly expresses change intent, aids code review
|
|
85
|
+
3. **Lowercase hyphens**: Avoids cross-platform filename issues
|
|
86
|
+
|
|
87
|
+
### Creating Change Package
|
|
88
|
+
|
|
89
|
+
After determining the change-id, call the scaffold script to initialize the change package:
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
change-scaffold.sh <change-id> --project-root <repo-root> --change-root <change-root> --truth-root <truth-root>
|
|
93
|
+
```
|
|
94
|
+
|
|
35
95
|
## Artifact Location
|
|
36
96
|
|
|
37
97
|
- Proposal: `<change-root>/<change-id>/proposal.md`
|