dev-playbooks 1.2.8 → 1.3.0

package/package.json

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

package/skills/_shared/references/spec-structure-template.md

@@ -0,0 +1,161 @@
+# Spec Structure Template
+
+> This template defines the standard structure for Spec truth files, ensuring Specs are verifiable, traceable, and can drive test generation.
+
+## File Location
+
+```
+<truth-root>/specs/<capability>/spec.md
+```
+
+## Standard Structure
+
+```markdown
+---
+# Metadata (required)
+capability: <capability-name>
+owner: @<owner>
+last_verified: YYYY-MM-DD
+last_referenced_by: <last-referencing-change-id>
+health: active | stale | deprecated
+freshness_check: monthly | quarterly | on-change
+---
+
+# <Capability Name> Specification
+
+## Glossary
+
+> Capability-specific terms, consistent with `<truth-root>/_meta/glossary.md`.
+
+| Term | Definition | Constraints |
+|------|------------|-------------|
+| Order | Order entity | Must have at least one OrderItem |
+| OrderItem | Order line item | qty > 0, price >= 0 |
+
+## Invariants
+
+> Constraints that must always hold; violations are system bugs.
+
+| ID | Description | Verification |
+|----|-------------|--------------|
+| INV-001 | Order total = SUM(item.price * item.qty) | A (automated test) |
+| INV-002 | Inventory quantity >= 0 | A (automated test) |
+| INV-003 | Shipped orders cannot be cancelled | A (state machine test) |
+
+## Contracts
+
+### Preconditions
+
+| ID | Operation | Condition | Violation Behavior |
+|----|-----------|-----------|-------------------|
+| PRE-001 | Create order | user.isAuthenticated | Return 401 |
+| PRE-002 | Pay order | order.status == 'pending' | Return 400 |
+
+### Postconditions
+
+| ID | Operation | Guarantee |
+|----|-----------|-----------|
+| POST-001 | Create order success | Generate unique order.id |
+| POST-002 | Payment success | inventory.decreased(qty) |
+
+## State Machine
+
+> If this capability involves state transitions, a state machine must be defined.
+
+### State Set
+
+```
+States: {Created, Paid, Shipped, Done, Cancelled}
+```
+
+### Transition Rules
+
+| Current State | Action | Target State | Condition |
+|---------------|--------|--------------|-----------|
+| Created | pay | Paid | payment.success |
+| Created | cancel | Cancelled | - |
+| Paid | ship | Shipped | inventory.reserved |
+| Paid | refund | Cancelled | - |
+| Shipped | deliver | Done | - |
+
+### Forbidden Transitions
+
+| Current State | Action | Reason |
+|---------------|--------|--------|
+| Shipped | cancel | Violates INV-003 |
+| Done | * | Terminal state, cannot exit |
+| Cancelled | * | Terminal state, cannot exit |
+
+## Requirements
+
+### REQ-001: <Requirement Title>
+
+**Description**: <one-sentence description>
+
+**SHALL/SHOULD/MAY**:
+- The system **SHALL** ...
+- The system **SHOULD** ...
+
+**Trace**: AC-001 (from design.md)
+
+#### Scenario: <scenario-name>
+
+- **GIVEN** user is logged in and cart is non-empty
+- **WHEN** user clicks "Submit Order"
+- **THEN** system creates order and returns order ID
+
+**Data Instances** (boundary conditions):
+
+| Input | Expected Output | Notes |
+|-------|-----------------|-------|
+| qty=1, price=100 | total=100 | Normal value |
+| qty=0 | Reject | Boundary - zero |
+| qty=-1 | Reject | Boundary - negative |
+
+---
+
+## Change History
+
+| Date | Change Package | Changes |
+|------|----------------|---------|
+| 2024-01-16 | 20240116-1030-add-cancel | Add cancel order scenario |
+```
+
+## Usage Guide
+
+### 1. Who Writes Specs?
+
+- **spec-contract skill**: Creates/updates spec deltas
+- **archiver skill**: Merges spec deltas into truth-root
+
+### 2. Who Reads Specs?
+
+| Skill | Reading Purpose |
+|-------|-----------------|
+| design-doc | Check if design conflicts with existing Specs, reference REQ-xxx |
+| test-owner | Generate tests from contracts/state machines |
+| impact-analysis | Identify affected Specs |
+| code-review | Check terminology consistency |
+| archiver | Update metadata, build reference chain |
+
+### 3. Test Generation Mapping
+
+| Spec Element | Generated Test Type |
+|--------------|---------------------|
+| INV-xxx | Invariant tests |
+| PRE-xxx | Precondition tests (satisfied + violated) |
+| POST-xxx | Postcondition tests |
+| State Transition | State transition tests |
+| Forbidden Transition | Forbidden transition tests |
+| Data Instance Table | Parameterized test cases |
+
+### 4. Health Detection
+
+The `health` field in Spec files is automatically detected by entropy-monitor:
+
+| Condition | health Status |
+|-----------|---------------|
+| last_verified < 90 days | `active` |
+| last_verified > 90 days | `stale` (needs review) |
+| Explicitly marked deprecated | `deprecated` |
+| last_referenced_by empty for >6 months | Recommend deletion |

package/skills/devbooks-archiver/SKILL.md

@@ -120,6 +120,32 @@ Merge change package spec artifacts into `<truth-root>`:
 | `<change-root>/<change-id>/specs/**` | `<truth-root>/specs/**` | Incremental merge |
 | `<change-root>/<change-id>/contracts/**` | `<truth-root>/contracts/**` | Versioned merge |
 
+**Spec Metadata Update** (must execute during merge):
+
+When merging specs into truth-root, the following metadata must be updated:
+
+```yaml
+# Update in each merged/referenced spec file header
+---
+last_referenced_by: <change-id>           # Last change package referencing this spec
+last_verified: <archive-date>             # Last verification date
+health: active                            # Health status: active | stale | deprecated
+---
+```
+
+**Metadata Update Rules**:
+
+| Scenario | Update Behavior |
+|----------|-----------------|
+| New Spec | Create complete metadata header |
+| Modify existing Spec | Update `last_referenced_by` and `last_verified` |
+| Spec referenced by design doc but not modified | Update only `last_referenced_by` |
+| Marked as deprecated | Set `health: deprecated` |
+
+**Building Reference Traceability Chain**:
+
+During archiving, archiver automatically scans the "Affected Specs" declared in design.md and updates the `last_referenced_by` field for these Specs, even if they weren't directly modified. This establishes a reverse traceability chain from Specs to change packages.
+
 ### Step 4: Architecture Merge
 
 > **Design Decision**: C4 architecture changes are recorded in design.md's Architecture Impact section and merged into truth by Archiver during archiving.

package/skills/devbooks-code-review/references/code-review-prompt.md

@@ -13,6 +13,10 @@ Inputs (provided by me):
 - Glossary / ubiquitous language (if present): `<truth-root>/_meta/glossary.md`
 - High-ROI pitfalls list (if present): `<truth-root>/engineering/pitfalls.md`
 
+**Required Spec Truth Reading** (mandatory before review):
+- `<truth-root>/specs/**`: existing spec files
+- Purpose: verify code naming/structure aligns with terminology and contracts defined in Specs
+
 Hard constraints (must follow):
 1) Output only review findings and concrete change suggestions; do not directly modify `tests/` or design documents.
 2) Do not debate business correctness (tests/specs decide that); focus only on maintainability and engineering quality.
@@ -64,6 +68,12 @@ Review focus (must cover):
 - Is the same concept named inconsistently across modules (e.g., User/Account/Member mixed)?
 - Is Entity vs Value Object modeled correctly? (Entity has an ID; VO has no ID and is immutable.)
 
+**Spec Truth Terminology Alignment** (must check):
+- Do code names match terminology defined in `<truth-root>/specs/`?
+- Do state names/enum values match state machine definitions in Specs?
+- Do method names reflect actions/transitions in Specs? (e.g., `cancel()` corresponds to `order --[cancel]--> cancelled`)
+- If naming inconsistencies are found, mark as "terminology drift risk" and recommend unification
+
 ---
 
 ## Invariant Protection (must check)

package/skills/devbooks-design-doc/references/design-doc-prompt.md

@@ -18,6 +18,10 @@ Inputs (provided by me):
 - Chat history
 - Glossary / ubiquitous language (if present): `<truth-root>/_meta/glossary.md`
 
+**Required Spec Truth Reading** (mandatory before designing):
+- `<truth-root>/specs/**`: existing spec files (REQ/Invariants/Contracts)
+- Purpose: ensure design does not conflict with existing specs and explicitly references affected specs
+
 Tasks:
 1) Output a design doc (not an implementation plan, not code).
 2) The doc must be concrete enough to drive acceptance and task decomposition: clear boundaries, contracts, red lines, and acceptance.
@@ -182,7 +186,13 @@ Limits:
 
 Additional requirements (for traceability in large projects):
 - Explicitly list affected capabilities/modules/external contracts (names and boundaries only; no implementation)
-- If external interfaces/APIs/events/data structures are involved: specify versioning strategy in the “Core data and event contracts” section (`schema_version`, compatibility window, migration/replay principles)
-- If architecture boundaries change: add an optional **C4 Delta** subsection under “Target architecture” describing what C1/C2/C3 elements were added/modified/removed (full maps are maintained by the C4 map maintainer)
+- If external interfaces/APIs/events/data structures are involved: specify versioning strategy in the "Core data and event contracts" section (`schema_version`, compatibility window, migration/replay principles)
+- If architecture boundaries change: add an optional **C4 Delta** subsection under "Target architecture" describing what C1/C2/C3 elements were added/modified/removed (full maps are maintained by the C4 map maintainer)
+
+**Spec Truth Reference Requirements** (core traceability):
+- **Must declare affected existing Specs**: list spec files under `<truth-root>/specs/` impacted by this design
+- **Must reference REQ/Invariant**: each constraint in the design must trace back to REQ-xxx or INV-xxx in Specs
+- **Gap declaration**: if design cannot satisfy an existing REQ, explicitly declare it as a Gap with justification
+- **Terminology consistency**: domain terms must match `<truth-root>/_meta/glossary.md`; new terms must be declared and proposed for glossary addition
 
 Now output the Design Doc in Markdown. Do not output extra explanations.

package/skills/devbooks-impact-analysis/references/impact-analysis-prompt.md

@@ -17,6 +17,10 @@ Input materials (provided by me):
 - Current truth source: `<truth-root>/`
 - Codebase (read-only analysis)
 
+**Required Spec Truth Reading** (mandatory before analysis):
+- `<truth-root>/specs/**`: existing spec files
+- Purpose: identify which existing Specs (REQ/Invariants/Contracts) are impacted by this change
+
 Hard constraints (must follow):
 - Impact analysis first, code later
 - No "decorative/surface refactors" unless they directly reduce risk for this change
@@ -53,6 +57,19 @@ Output format (MECE):
        - Are external system/API changes isolated by ACL? (External model changes must not leak into internal models)
        - Are there direct calls to external APIs bypassing the adapter layer?
        - If adding external dependency: suggested ACL interface definition
+   - **F. Affected Spec Truth** (required):
+     - List spec files under `<truth-root>/specs/` impacted by this change
+     - For each affected Spec, mark impact type:
+       - `[BREAK]`: breaks existing REQ/Invariant (needs Spec update or redesign)
+       - `[EXTEND]`: extends existing capability (needs new REQ/Scenario)
+       - `[DEPRECATE]`: deprecates existing capability (needs Spec marked deprecated)
+     - Output format:
+       ```
+       Affected Specs:
+       - [EXTEND] specs/order/spec.md - add cancel order scenario
+       - [BREAK] specs/payment/spec.md - INV-002 "paid orders cannot be cancelled" needs modification
+       - [DEPRECATE] specs/legacy-checkout/spec.md - entire spec deprecated
+       ```
 4) Compatibility and Risks
    - Breaking changes (explicitly mark if any)
    - Migration/rollback paths

package/skills/devbooks-spec-contract/references/spec-change-prompt.md

@@ -18,6 +18,10 @@ Inputs (provided by me):
 - Project profile (if present; follow formatting conventions first): `<truth-root>/_meta/project-profile.md`
 - Glossary / ubiquitous language (if present): `<truth-root>/_meta/glossary.md`
 
+**Spec Truth Conflict Detection** (must complete before writing):
+- **Must read existing Specs**: before writing spec delta, read all specs under `<truth-root>/specs/**`
+- **Purpose**: detect conflicts between new spec delta and existing Specs
+
 Hard constraints (must follow):
 - Output a **spec delta**, not a design doc, not an implementation plan, not code
 - Do not write implementation details (class names/function names/specific production file paths/library calls)
@@ -26,6 +30,13 @@ Hard constraints (must follow):
 - Avoid duplicating capabilities: search/reuse/modify existing capability specs first; create a new capability only when necessary
 - Ubiquitous language: if `<truth-root>/_meta/glossary.md` exists, you must use those terms; do not invent new terms
 
+**Conceptual Integrity Guardian** (conflict detection rules):
+- **Terminology conflict**: does the new spec use terminology inconsistent with existing specs? (e.g., `Order.status` vs `Order.state`)
+- **Rule conflict**: do new spec rules contradict existing spec rules? (e.g., "paid orders can be cancelled" vs "paid orders cannot be cancelled")
+- **Boundary conflict**: does the new spec's responsibility overlap with existing specs? (e.g., two specs both claim ownership of payment logic)
+- **Invariant compatibility**: does the new spec violate Invariants declared in existing specs?
+- **Conflict report**: if conflicts are detected, declare them at the top of the spec delta with resolution suggestions; archiving is forbidden until conflicts are resolved
+
 Workshop (internal step; do not output separately):
 - Before writing the spec, run a “virtual three-amigos workshop” (business/dev/test) and incorporate consensus + edge examples into Requirements/Scenarios; do not output workshop notes.
 

package/skills/devbooks-test-owner/references/test-code-prompt.md

@@ -11,6 +11,10 @@ Inputs (provided by me):
 - Design/spec documents
 - Test methodology references (see: `references/test-driven-development.md`)
 
+**Required Spec Truth Reading** (mandatory before testing):
+- `<truth-root>/specs/**`: existing spec files
+- Purpose: auto-generate test skeletons from contracts (Preconditions/Postconditions/Invariants) and state machines
+
 Artifact locations (directory conventions; protocol-agnostic):
 - Test plan + traceability should live at: `<change-root>/<change-id>/verification.md`
 - Test code changes live in the repo’s normal place (e.g., `tests/`), but traceability matrices and MANUAL-* checklists should live in the change package (`verification.md`), not scattered into external `docs/`
@@ -63,6 +67,16 @@ Core principles (must follow):
 3) **Deterministic and reproducible**: default to offline, no real external services; freeze time; fix random seeds; use fakes/mocks; fixed inputs.
 4) **Few but strong (risk-driven)**: prioritize the highest-risk failure modes (isolation, idempotency/replay, quality gates, error cascades, contract drift).
 
+**Contract Tests from Spec Truth** (must follow):
+- **Invariants → invariant tests**: each `[Invariant]` or `INV-xxx` in Specs must have a corresponding test
+- **Preconditions → precondition tests**: each `PRE-xxx` generates two tests: (1) success when satisfied (2) rejection when violated
+- **Postconditions → postcondition tests**: each `POST-xxx` generates result verification tests
+- **State Machine → transition tests**: if Spec contains state machine, generate:
+  - All legal transition path tests
+  - All forbidden transition rejection tests
+  - Terminal state cannot exit tests
+- **REQ coverage traceability**: each test must annotate which REQ-xxx/INV-xxx/PRE-xxx/POST-xxx it covers (in comments or verification.md)
+
 Coverage targets (debate edition; guidance only):
 
 | Code type | Coverage target | Rationale |