dev-playbooks 1.2.5 → 1.2.6

package/package.json

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

package/skills/devbooks-code-review/SKILL.md

@@ -10,6 +10,34 @@ allowed-tools:
 
 # DevBooks: Code Review (Reviewer)
 
+## Workflow Position Awareness
+
+> **Core Principle**: Code Review executes after Test Owner Phase 2 verification, as the final review step before archiving.
+
+### My Position in the Overall Workflow
+
+```
+proposal → design → test-owner(phase1) → coder → test-owner(phase2) → [Code Review] → archive
+                                                                          ↓
+                                                              Readability/consistency/dependency review
+```
+
+### Code Review's Responsibility Boundaries
+
+| Allowed | Prohibited |
+|---------|------------|
+| Review code readability/consistency | ❌ Modify code files |
+| Set verification.md Status = Done | ❌ Discuss business correctness (that's Test Owner's job) |
+| Suggest improvements | ❌ Check off AC coverage matrix (that's Test Owner's job) |
+
+### Prerequisites
+
+- [ ] Test Owner Phase 2 completed (AC matrix checked)
+- [ ] Tests all green
+- [ ] evidence/green-final/ exists
+
+---
+
 ## Prerequisites: Configuration Discovery (Protocol Agnostic)
 
 - `<truth-root>`: Current truth directory root

package/skills/devbooks-coder/SKILL.md

@@ -12,6 +12,40 @@ allowed-tools:
 
 # DevBooks: Implementation Lead (Coder)
 
+## Workflow Position Awareness
+
+> **Core Principle**: Coder executes after Test Owner Phase 1 and hands off to Test Owner Phase 2 for verification upon completion.
+
+### My Position in the Overall Workflow
+
+```
+proposal → design → test-owner(phase1) → [Coder] → test-owner(phase2) → code-review → archive
+                                            ↓
+                                    Implement code, make tests green
+```
+
+### Coder's Responsibility Boundaries
+
+| Allowed | Prohibited |
+|---------|------------|
+| Modify `src/**` code | ❌ Modify `tests/**` |
+| Check off `tasks.md` items | ❌ Modify `verification.md` |
+| Record deviations to `deviation-log.md` | ❌ Check off AC coverage matrix |
+| Run tests to verify | ❌ Set verification.md Status |
+
+### Flow After Coder Completes
+
+1. **Tasks complete**: tasks.md all `[x]`
+2. **Tests green**: Run `npm test` to confirm passing
+3. **Hand off to Test Owner**: Notify Test Owner to enter Phase 2 verification
+4. **Wait for verification result**:
+   - Test Owner confirms green → Proceed to Code Review
+   - Test Owner finds issues → Coder fixes
+
+**Key Reminder**: After Coder completes, **do not go directly to Code Review**, first let Test Owner verify and check off.
+
+---
+
 ## Prerequisites: Configuration Discovery (Protocol-Agnostic)
 
 - `<truth-root>`: Current truth directory root
@@ -334,8 +368,8 @@ Run devbooks-xxx skill for change <change-id>
 
 | My Status | Next Step | Reason |
 |-----------|-----------|--------|
-| COMPLETED | `devbooks-code-review` | Review readability/consistency |
-| COMPLETED_WITH_DEVIATION | `devbooks-design-backport` | Backport design first, then review |
+| COMPLETED | `devbooks-test-owner` (Phase 2 verification) | Tasks complete, need Test Owner to verify and check off |
+| COMPLETED_WITH_DEVIATION | `devbooks-design-backport` | Backport design first, then let Test Owner verify |
 | HANDOFF (test issue) | `devbooks-test-owner` | Coder cannot modify tests |
 | BLOCKED | Wait for user | Record breakpoint area |
 | FAILED | Fix and retry | Analyze failure reason |
@@ -344,6 +378,7 @@ Run devbooks-xxx skill for change <change-id>
 - Coder **can never modify** `tests/**`
 - If test issues found, must HANDOFF to Test Owner (separate session)
 - If deviations exist, must design-backport first before continuing
+- **Coder must go through Test Owner Phase 2 verification before Code Review**
 
 ---
 

package/skills/devbooks-design-backport/SKILL.md

@@ -11,6 +11,40 @@ allowed-tools:
 
 # DevBooks: Design Backport
 
+## Workflow Position Awareness
+
+> **Core Principle**: Design Backport is now **primarily auto-invoked by Spec Gardener during archive phase**, users typically don't need to call it manually.
+
+### My Position in the Overall Workflow
+
+```
+proposal → design → test-owner → coder → test-owner(verify) → code-review → [Archive/Spec Gardener]
+                                    ↓                                              ↓
+                             Record deviations to deviation-log.md     Auto-invoke design-backport
+```
+
+### Design Decision: Auto Backport
+
+**Old Flow** (manual judgment required):
+```
+coder has deviations → user manually calls design-backport → then archive
+```
+
+**New Flow** (auto handling):
+```
+coder has deviations → spec-gardener auto-detects and backports during archive → archive
+```
+
+### When Manual Call is Still Needed
+
+| Scenario | Need Manual Call? |
+|----------|-------------------|
+| Normal flow (deviations in deviation-log.md) | ❌ Auto-handled during archive |
+| Need immediate backport (don't wait for archive) | ✅ Manual call |
+| Severe design-implementation conflict needs decision | ✅ Manual call and discuss |
+
+---
+
 ## Prerequisites: Configuration Discovery (Protocol-Agnostic)
 
 - `<truth-root>`: Current truth directory root

package/skills/devbooks-design-doc/SKILL.md

@@ -11,6 +11,28 @@ allowed-tools:
 
 # DevBooks: Design Document (Design Doc)
 
+## Workflow Position Awareness
+
+> **Core Principle**: Design Doc executes after Proposal is approved, serving as the starting point for implementation phase.
+
+### My Position in the Overall Workflow
+
+```
+proposal → [Design Doc] → spec-contract → implementation-plan → test-owner → coder → ...
+                 ↓
+        Define What/Constraints/AC
+```
+
+### Design Doc's Output
+
+- **What**: What to do (not how to do it)
+- **Constraints**: Constraint conditions
+- **AC-xxx**: Acceptance criteria (testable)
+
+**Key**: Design Doc does not write implementation steps, that's implementation-plan's responsibility.
+
+---
+
 ## Prerequisites: Configuration Discovery (Protocol Agnostic)
 
 - `<truth-root>`: Current truth directory root

package/skills/devbooks-implementation-plan/SKILL.md

@@ -11,6 +11,42 @@ allowed-tools:
 
 # DevBooks: Implementation Plan
 
+## Workflow Position Awareness
+
+> **Core Principle**: Implementation Plan executes after Design Doc, providing task list for Test Owner and Coder.
+
+### My Position in the Overall Workflow
+
+```
+proposal → design → [Implementation Plan] → test-owner(phase1) → coder → ...
+                            ↓
+                    tasks.md (task list)
+```
+
+### Implementation Plan's Responsibilities
+
+| Allowed | Prohibited |
+|---------|------------|
+| Derive tasks from design.md | ❌ Reference tests/ (avoid implementation bias) |
+| Bind acceptance anchors (AC-xxx) | ❌ Write implementation code |
+| Split parallel tasks | ❌ Execute tasks |
+
+### Output: tasks.md Structure
+
+```markdown
+## Main Plan Area
+- [ ] MP1.1 Task description (AC-001)
+- [ ] MP1.2 Task description (AC-002)
+
+## Temporary Plan Area
+(urgent tasks)
+
+## Breakpoint Area
+(context switch resume info)
+```
+
+---
+
 ## Prerequisites: Configuration Discovery (Protocol-Agnostic)
 
 - `<truth-root>`: Current truth directory root

package/skills/devbooks-spec-gardener/SKILL.md

@@ -11,6 +11,36 @@ allowed-tools:
 
 # DevBooks: Spec Gardener
 
+## Workflow Position Awareness
+
+> **Core Principle**: Spec Gardener is the endpoint of the archive phase, responsible for merging change package artifacts into truth, **and automatically handling any pending backports**.
+
+### My Position in the Overall Workflow
+
+```
+proposal → design → test-owner → coder → test-owner(verify) → code-review → [Spec Gardener/Archive]
+                                                                                    ↓
+                                                               Auto backport + Merge to truth + Archive
+```
+
+### Spec Gardener's Responsibilities
+
+1. **Auto backport detection**: Check if deviation-log.md has pending backport records
+2. **Auto execute backport**: If pending records exist, automatically execute design backport
+3. **Merge to truth**: Merge specs/contracts/architecture into truth-root
+4. **Archive change package**: Set verification.md Status = Archived
+
+### Why Auto Backport in Archive Phase?
+
+**Design Decision**: Users only need to call skills linearly, no need to judge whether backport is needed.
+
+| Scenario | Old Design (Manual judgment) | New Design (Auto handling) |
+|----------|------------------------------|---------------------------|
+| Coder has deviations | User needs to call design-backport → then archive | Spec Gardener auto-detects and backports |
+| Coder has no deviations | Archive directly | Archive directly |
+
+---
+
 ## Prerequisites: Configuration Discovery (Protocol Agnostic)
 
 - `<truth-root>`: Current truth directory root
@@ -31,6 +61,51 @@ Before execution, **must** search for configuration in the following order (stop
 
 ## Core Responsibilities
 
+### 0. Auto Backport Detection and Handling (Required Before Archive)
+
+> **Design Decision**: Archive phase automatically handles all pending backports, users don't need to manually call design-backport.
+
+**Detection Flow**:
+
+```
+1. Read <change-root>/<change-id>/deviation-log.md
+2. Check if there are "| ❌" pending backport records
+   → Yes: Execute auto backport (steps 3-5)
+   → No: Skip, proceed directly to merge phase
+
+3. For each pending record, determine if it's Design-level content:
+   - DESIGN_GAP, CONSTRAINT_CHANGE, API_CHANGE → Need backport
+   - Pure implementation details (filename/classname/temp steps) → Don't backport, mark as IMPL_ONLY
+
+4. Execute design backport:
+   - Read design.md
+   - Update according to design-backport protocol's "backportable content scope"
+   - Add change record at the end of design.md
+
+5. Update deviation-log.md:
+   - Mark backported records as ✅
+   - Record backport time and archive batch
+```
+
+**Auto Backport Content Scope** (inherited from design-backport):
+
+| Backportable | Not Backportable |
+|--------------|------------------|
+| External semantics/user-visible behavior | Specific file paths, class/function names |
+| System-level immutable constraints (Invariants) | PR splits, task execution order |
+| Core data contracts and evolution strategies | Overly detailed algorithm pseudocode |
+| Cross-phase governance strategies | Script commands |
+| Key tradeoffs and decisions | Table/field names |
+
+**deviation-log.md Update Format**:
+
+```markdown
+| Time | Type | Description | Affected Files | Backported | Batch |
+|------|------|-------------|----------------|:----------:|-------|
+| 2024-01-15 10:30 | DESIGN_GAP | Concurrent scenario | tests/... | ✅ | archive-2024-01-16 |
+| 2024-01-15 11:00 | IMPL_ONLY | Variable rename | src/... | ⏭️ | (skipped) |
+```
+
 ### 1. Spec Merge and Maintenance
 
 During archive phase, merge change package spec artifacts into `<truth-root>`:
@@ -106,10 +181,34 @@ Detection rules reference: `skills/_shared/context-detection-template.md`
 
 | Mode | Trigger Condition | Behavior |
 |------|-------------------|----------|
-| **Archive Mode** | change-id provided and gates pass | Merge change package artifacts into truth-root |
+| **Archive Mode** | change-id provided and gates pass | **Auto backport** → Merge to truth-root → Set Status=Archived |
 | **Maintenance Mode** | No change-id | Execute deduplication, cleanup, organization operations |
 | **Check Mode** | With --dry-run parameter | Output suggestions only, no actual modifications |
 
+### Archive Mode Complete Flow
+
+```
+1. Pre-checks:
+   - [ ] Change package exists
+   - [ ] verification.md Status = Ready or Done
+   - [ ] evidence/green-final/ exists
+   - [ ] tasks.md all [x]
+
+2. Auto backport (if needed):
+   - [ ] Detect deviation-log.md
+   - [ ] Backport to design.md
+   - [ ] Update deviation-log.md marks
+
+3. Merge to truth:
+   - [ ] Merge specs/**
+   - [ ] Merge contracts/**
+   - [ ] Merge Architecture Impact to c4.md
+
+4. Archive:
+   - [ ] Set verification.md Status = Archived
+   - [ ] Output archive report
+```
+
 ### Detection Output Example
 
 ```

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

@@ -12,6 +12,46 @@ allowed-tools:
 
 # DevBooks: Test Owner
 
+## Workflow Position Awareness
+
+> **Core Principle**: Test Owner has **dual-phase responsibilities** in the overall workflow, ensuring role isolation from Coder.
+
+### My Position in the Overall Workflow
+
+```
+proposal → design → [Test Owner Phase 1] → coder → [Test Owner Phase 2] → code-review → archive
+                         ↓                              ↓
+                    Red baseline output          Green verification + check off
+```
+
+### Test Owner's Dual-Phase Responsibilities
+
+| Phase | Trigger | Core Responsibility | Output |
+|-------|---------|---------------------|--------|
+| **Phase 1: Red Baseline** | After design.md is complete | Write tests, produce failure evidence | verification.md (Status=Ready), Red baseline |
+| **Phase 2: Green Verification** | After Coder completes | Verify tests pass, check off AC matrix | AC matrix checked, Status remains Ready (wait for Reviewer to set Done) |
+
+### Phase 2 Detailed Responsibilities (Critical!)
+
+When user says "Coder is done, please verify" or similar, Test Owner enters **Phase 2**:
+
+1. **Run all tests**: Execute `npm test` or project test command
+2. **Verify Green status**: Confirm all tests pass
+3. **Check off AC Coverage Matrix**: Change `[ ]` to `[x]` in verification.md AC Coverage Matrix
+4. **Collect Green evidence**: Save to `evidence/green-final/`
+5. **Output verification report**: Summarize test results and coverage
+
+### AC Coverage Matrix Checkbox Permissions (Important!)
+
+| Checkbox Location | Who Can Check | When to Check |
+|-------------------|---------------|---------------|
+| `[ ]` in AC Coverage Matrix | **Test Owner** | Phase 2 after verifying Green status |
+| Status field `Done` | Reviewer | After Code Review passes |
+
+**Prohibited**: Coder cannot check AC Coverage Matrix, cannot modify verification.md.
+
+---
+
 ## Prerequisites: Configuration Discovery (Protocol-Agnostic)
 
 - `<truth-root>`: Current truth directory root
@@ -339,28 +379,53 @@ During test writing, you **must immediately** write to `deviation-log.md` in the
 
 ## Completion Status and Routing
 
-### Completion Status Classification (MECE)
+### Phase Awareness (Critical!)
+
+Test Owner has two phases, completion status varies by phase:
+
+| Current Phase | How to Determine | Next Step After Completion |
+|---------------|------------------|---------------------------|
+| **Phase 1** | verification.md doesn't exist or Red baseline not produced | → Coder |
+| **Phase 2** | User says "verify/check off" and Coder has completed | → Code Review |
+
+### Phase 1 Completion Status Classification (MECE)
 
 | Code | Status | Determination Criteria | Next Step |
 |:----:|--------|------------------------|-----------|
-| ✅ | COMPLETED | Red baseline produced, no deviations | `devbooks-coder` (separate session) |
-| ⚠️ | COMPLETED_WITH_DEVIATION | Red baseline produced, deviation-log has pending records | `devbooks-design-backport` |
+| ✅ | PHASE1_COMPLETED | Red baseline produced, no deviations | `devbooks-coder` (separate session) |
+| ⚠️ | PHASE1_COMPLETED_WITH_DEVIATION | Red baseline produced, deviation-log has pending records | `devbooks-design-backport` |
 | ❌ | BLOCKED | Needs external input/decision | Record breakpoint, wait for user |
 | 💥 | FAILED | Test framework issues etc. | Fix and retry |
 
-### Status Determination Flow
+### Phase 2 Completion Status Classification (MECE)
 
-```
-1. Check if deviation-log.md has "| ❌" records
-   → Yes: COMPLETED_WITH_DEVIATION
+| Code | Status | Determination Criteria | Next Step |
+|:----:|--------|------------------------|-----------|
+| ✅ | PHASE2_VERIFIED | Tests all green, AC matrix checked | `devbooks-code-review` |
+| ❌ | PHASE2_FAILED | Tests not passing | Notify Coder to fix, or HANDOFF |
+| 🔄 | PHASE2_HANDOFF | Found issues with tests themselves | Fix tests then re-verify |
 
-2. Check if Red baseline is produced
-   - verification.md exists with traceability matrix
-   - evidence/red-baseline/ exists
-   → No: BLOCKED or FAILED
+### Phase Determination Flow
 
-3. All checks passed
-   → COMPLETED
+```
+1. Check which phase we're in:
+   - verification.md doesn't exist → Phase 1
+   - verification.md exists but AC matrix all [ ] → Phase 1 or Phase 2 (depends on user request)
+   - User explicitly says "verify/check off/Coder is done" → Phase 2
+
+2. Phase 1 status determination:
+   a. Check if deviation-log.md has "| ❌" records
+      → Yes: PHASE1_COMPLETED_WITH_DEVIATION
+   b. Check if Red baseline is produced
+      → No: BLOCKED or FAILED
+   c. All above pass → PHASE1_COMPLETED
+
+3. Phase 2 status determination:
+   a. Run tests, check if all green
+      → No: PHASE2_FAILED
+   b. Check if tests themselves have issues
+      → Yes: PHASE2_HANDOFF
+   c. All green and no issues → PHASE2_VERIFIED
 ```
 
 ### Routing Output Template (Required)
@@ -370,15 +435,21 @@ After completing test-owner, **must** output in this format:
 ```markdown
 ## Completion Status
 
-**Status**: ✅ COMPLETED / ⚠️ COMPLETED_WITH_DEVIATION / ❌ BLOCKED / 💥 FAILED
+**Phase**: Phase 1 (Red Baseline) / Phase 2 (Green Verification)
+
+**Status**: ✅ PHASE1_COMPLETED / ✅ PHASE2_VERIFIED / ⚠️ ... / ❌ ... / 💥 ...
+
+**Red Baseline**: Produced / Not completed (Phase 1 only)
+
+**Green Verification**: All green / Has failures (Phase 2 only)
 
-**Red Baseline**: Produced / Not completed
+**AC Matrix**: Checked N/M / Not checked (Phase 2 only)
 
 **Deviation Records**: Has N pending / None
 
 ## Next Step
 
-**Recommended**: `devbooks-xxx skill` (separate session)
+**Recommended**: `devbooks-xxx skill`
 
 **Reason**: [specific reason]
 
@@ -390,8 +461,11 @@ Run devbooks-xxx skill for change <change-id>
 
 | My Status | Next Step | Reason |
 |-----------|-----------|--------|
-| COMPLETED | `devbooks-coder` (separate session) | Red baseline produced, Coder implements to make Green |
-| COMPLETED_WITH_DEVIATION | `devbooks-design-backport` | Backport design first, then hand to Coder |
+| PHASE1_COMPLETED | `devbooks-coder` (separate session) | Red baseline produced, Coder implements to make Green |
+| PHASE1_COMPLETED_WITH_DEVIATION | `devbooks-design-backport` | Backport design first, then hand to Coder |
+| PHASE2_VERIFIED | `devbooks-code-review` | Tests all green, can proceed to code review |
+| PHASE2_FAILED | Notify Coder | Tests not passing, need Coder to fix |
+| PHASE2_HANDOFF | Fix tests | Tests themselves have issues, Test Owner fixes |
 | BLOCKED | Wait for user | Record breakpoint area |
 | FAILED | Fix and retry | Analyze failure reason |
 
@@ -399,6 +473,7 @@ Run devbooks-xxx skill for change <change-id>
 - **Role Isolation**: Coder must work in a **separate conversation/instance**
 - Test Owner and Coder cannot share the same session context
 - If deviations exist, must design-backport first before handing to Coder
+- **Phase 2 AC matrix checking can only be done by Test Owner**
 
 ---