dev-playbooks 2.2.1 → 2.3.0

package/skills/devbooks-router/references/routing-rules-and-templates.md

@@ -0,0 +1,120 @@
+# Router: routing rules and output templates (reference)
+
+This file carries the detailed rules and examples for Router, to keep `skills/devbooks-router/SKILL.md` small and stable.
+
+## Config discovery (protocol-agnostic, mandatory)
+
+- `<truth-root>`: truth directory root
+- `<change-root>`: change package root
+
+Discovery order (stop at the first match):
+1. `.devbooks/config.yaml` (if exists) → parse mappings
+2. `dev-playbooks/project.md` (if exists) → Dev-Playbooks default mapping
+3. `project.md` (if exists) → template default mapping
+4. If still unknown → stop and ask the user
+
+Constraints:
+- If `agents_doc` is specified, read it before doing anything.
+- Do not guess directory roots.
+
+## Structured analysis capability check (automatic)
+
+Before routing, check whether structured code analysis is available (dependency/ref tracking):
+
+- If unavailable: warn that impact analysis/review will degrade to text search; continue routing.
+- If available: continue silently.
+
+## Output template (mandatory)
+
+1) Ask 2 minimum key questions (skip if already known from context):
+- What is the `<change-id>`?
+- What are the final values of `<truth-root>` / `<change-root>` in this project?
+
+2) Output 3–6 next-step routing items:
+- Each item: Skill to use + artifact path + why it’s needed.
+
+3) If the user asks to “start producing file content”, switch to the target Skill’s output mode.
+
+## Default routing rules
+
+### A) Proposal phase
+
+Signals: “proposal/why/risks/scope/refactor proposal/don’t write code yet”.
+
+Default:
+- `devbooks-proposal-author` → `(<change-root>/<change-id>/proposal.md)`
+- `devbooks-design-doc` → `(<change-root>/<change-id>/design.md)`
+- `devbooks-implementation-plan` → `(<change-root>/<change-id>/tasks.md)`
+
+Add when needed:
+- cross-module / unclear impact → `devbooks-impact-analysis`
+- high risk / trade-offs → `devbooks-proposal-challenger` + `devbooks-proposal-judge`
+- external behavior / contract change → `devbooks-spec-contract` → `(<change-root>/<change-id>/specs/**)`
+
+### B) Apply phase (Test Owner / Coder)
+
+Signals: “start implementing/run tests/fix failures/make gates green”.
+
+Default (role isolation):
+- Test Owner (separate conversation): `devbooks-test-owner` → `(<change-root>/<change-id>/verification.md)` + `tests/**`
+- Coder (separate conversation): `devbooks-coder` (must not modify `tests/**`)
+
+### C) Review phase
+
+Signals: “review/maintainability/smells/consistency”.
+
+Default:
+- `devbooks-reviewer`
+- `devbooks-test-reviewer`
+
+### D) Docs sync
+
+Signals: “update docs/sync docs/README update”.
+
+Default:
+- `devbooks-docs-consistency`
+
+### E) Archive phase
+
+Signals: “archive/close the loop/merge specs”.
+
+Default:
+- `devbooks-archiver`
+
+Pre-archive check (recommended):
+- `change-check.sh <change-id> --mode strict ...`
+
+### F) Prototype track
+
+Signals: “prototype/spike/throwaway prototype/--prototype”.
+
+Default:
+1. `change-scaffold.sh <change-id> --prototype ...`
+2. Test Owner: `devbooks-test-owner --prototype`
+3. Coder: `devbooks-coder --prototype` (write under `(<change-root>/<change-id>/prototype/src/)`)
+4. Promote explicitly: `prototype-promote.sh <change-id>`
+
+## Optional: Impact profile parsing
+
+If `proposal.md` includes an `impact_profile:` YAML block, Router can use it to refine routing.
+
+Example:
+```yaml
+impact_profile:
+  external_api: true/false
+  architecture_boundary: true/false
+  data_model: true/false
+  cross_repo: true/false
+  risk_level: high/medium/low
+  affected_modules:
+    - name: <module-path>
+      type: add/modify/delete
+      files: <count>
+```
+
+## Context detection (resume)
+
+Infer phase from existing artifacts:
+- `proposal.md`, `design.md`, `tasks.md`, `verification.md`
+- `evidence/green-final/`
+

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

@@ -12,7 +12,28 @@ allowed-tools:
 
 # DevBooks: Spec & Contract
 
-> This skill combines the functionality of the original `devbooks-spec-delta` and `devbooks-contract-data`, reducing decision fatigue.
+## Progressive Disclosure
+
+### Base (Required)
+Goal: Produce a spec delta and external contract notes for a change, without implementation steps.
+Inputs: `proposal.md`, `design.md`, existing truth specs, and change scope.
+Outputs: spec deltas under `<change-root>/<change-id>/specs/<capability>/spec.md` and contract notes (as required).
+Boundaries: spec stage only; do not write implementation steps; do not modify code or `tests/**`.
+Evidence: reference spec paths, contract IDs, and evidence outputs.
+
+### Advanced (Optional)
+Use when you need: compatibility strategy, migration notes, implicit change detection.
+
+### Extended (Optional)
+Use when you need: faster search/impact via optional MCP capabilities.
+
+## Recommended MCP Capability Types
+- Code search (code-search)
+- Reference tracking (reference-tracking)
+- Impact analysis (impact-analysis)
+- Doc retrieval (doc-retrieval)
+
+> This skill combines the functionality of the original `devbooks-spec-delta` and `devbooks-contract-data`.
 
 ## Prerequisites: Configuration Discovery (Protocol-Agnostic)
 
@@ -178,48 +199,11 @@ After completing spec-contract, output:
 
 **Next: `devbooks-implementation-plan`**
 
-Reason: Spec and contract are now defined. The next step is to create an implementation plan (tasks.md) that breaks down the work into trackable tasks with verification anchors.
+Next: Create an implementation plan (`tasks.md`) with trackable tasks and acceptance anchors.
 
 ### How to invoke
 ```
 Run devbooks-implementation-plan skill for change <change-id>
 ```
-```
 
 ---
-
-## MCP Enhancement
-
-This Skill supports MCP runtime enhancement, automatically detecting and enabling advanced features.
-
-MCP enhancement rules reference: `skills/_shared/mcp-enhancement-template-mcp-enhancement.md`
-
-### Dependent MCP Services
-
-| Service | Purpose | Timeout |
-|---------|---------|---------|
-| `mcp__ckb__findReferences` | Detect contract reference scope | 2s |
-| `mcp__ckb__getStatus` | Detect CKB index availability | 2s |
-
-### Detection Process
-
-1. Call `mcp__ckb__getStatus` (2s timeout)
-2. If CKB available -> Use `findReferences` to detect reference scope of contract symbols
-3. If timeout or failure -> Fallback to Grep text search
-
-### Enhanced Mode vs Basic Mode
-
-| Feature | Enhanced Mode | Basic Mode |
-|---------|---------------|------------|
-| Reference detection | Symbol-level precise matching | Grep text search |
-| Contract impact scope | Call graph analysis | Direct reference counting |
-| Compatibility risk | Automatic assessment | Manual judgment |
-
-### Fallback Notice
-
-When MCP is unavailable, output the following notice:
-
-```
-Warning: CKB unavailable, using Grep text search for contract reference detection.
-Results may be less precise. Consider manually generating SCIP index for more precise results.
-```

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

@@ -12,325 +12,84 @@ allowed-tools:
 
 # DevBooks: Test Owner
 
-## Quick Start
+## Progressive Disclosure
 
-My responsibilities:
-1. **Phase 1 (Red Baseline)**: Write tests → Produce failure evidence
-2. **Phase 2 (Green Verification)**: Audit evidence → Check off AC matrix
+### Base (Required)
+Goal: Author acceptance tests and `verification.md`, produce a Red baseline first, then audit Green evidence before checking off the AC matrix.
+Inputs: design/specs, change package context, project test conventions.
+Outputs: `tests/**`, `<change-root>/<change-id>/verification.md`, evidence logs under `evidence/red-baseline/` and `evidence/green-final/`.
+Boundaries: do not modify implementation code (e.g. `src/**`); do not edit `tasks.md`.
+Evidence: reference test logs and evidence paths.
 
-## Workflow Position
+### Advanced (Optional)
+Use when you need: test layering, edge cases, isolation techniques, deviation routing.
 
-```
-proposal → design → [TEST-OWNER] → [CODER] → [TEST-OWNER] → code-review → archive
-                         ↓              ↓           ↓
-                    Red baseline    Implement    Evidence audit
-                   (incremental)   (@smoke)     (no @full rerun)
-```
+### Extended (Optional)
+Use when you need: faster search/impact via optional MCP capabilities.
 
-## Dual-Phase Responsibilities
+## Recommended MCP Capability Types
 
-| Phase | Trigger | Core Responsibility | Test Run Method | Output |
-|-------|---------|---------------------|-----------------|--------|
-| **Phase 1: Red Baseline** | After design.md is complete | Write tests, produce failure evidence | Only run **incremental tests** (new/P0) | verification.md (Status=Ready), Red baseline |
-| **Phase 2: Green Verification** | After Coder completes + @full passes | **Audit evidence**, check off AC matrix | Default no rerun, optional sampling | AC matrix checked, Status=Verified |
+- Code search (code-search)
+- Reference tracking (reference-tracking)
+- Impact analysis (impact-analysis)
 
-### AI Era Optimization
+## Role Isolation (Mandatory)
 
-| Old Design | New Design | Reason |
-|------------|------------|--------|
-| Test Owner and Coder must use separate sessions | Same session, switch with `[TEST-OWNER]` / `[CODER]` mode labels | Reduce context rebuilding cost |
-| Phase 2 reruns full tests | Phase 2 defaults to **evidence audit**, optional sampling rerun | Avoid slow test multiple runs |
-| No test layering requirement | Mandatory test layering: `@smoke`/`@critical`/`@full` | Fast feedback loop |
+- Test Owner and Coder must be separate conversations/instances.
+- Do not switch roles within one conversation.
+- This role only produces `tests/**` and `verification.md`.
 
----
-
-## Prerequisites: Configuration Discovery
-
-- `<truth-root>`: Current truth directory root
-- `<change-root>`: Change package directory root
-
-Before execution, **must** search for configuration in the following order (stop when found):
-1. `.devbooks/config.yaml` (if exists) → Parse and use its mappings
-2. `dev-playbooks/project.md` (if exists) → Dev-Playbooks protocol, use default mappings
-3. `project.md` (if exists) → Template protocol, use default mappings
-4. If still unable to determine → **Stop and ask user**
-
-**Key Constraints**:
-- If `agents_doc` (rules document) is specified in configuration, **must read that document first** before performing any operations
-- Do not guess directory roots
-
-## Artifact Locations
-
-- Test plan and traceability: `<change-root>/<change-id>/verification.md`
-- Test code: Per repository conventions (e.g., `tests/**`)
-- Red baseline evidence: `<change-root>/<change-id>/evidence/red-baseline/`
-- Green evidence: `<change-root>/<change-id>/evidence/green-final/`
-
----
-
-## 📚 Reference Documentation
-
-### Must Read (Read Immediately)
+## Core Responsibilities
 
-1. **AI Behavior Guidelines**: `~/.claude/skills/_shared/references/ai-behavior-guidelines.md`
-   - Verifiability gating, structural quality gating, completeness gating
-   - Foundation rules for all skills
+- Maintain `<change-root>/<change-id>/verification.md` (traceability + status).
+- Phase 1 (Red baseline): write tests and capture failing evidence.
+- Phase 2 (Green verification): audit Green evidence after full gates pass, then check off the AC matrix.
+- Record design/spec gaps to `deviation-log.md` for backporting.
 
-2. **Absolute Rules and Constraints**: `references/absolute-rules-and-constraints.md`
-   - No stub tests, no demo mode, tests must not be decoupled from AC
-   - AC coverage matrix checkbox permissions
-   - Test isolation and stability requirements
+## Hard Boundaries
 
-3. **Test Code Prompt**: `references/test-code-prompt.md`
-   - Complete test writing guide
-   - Strictly follow this prompt
-
-### Read as Needed for Phase 1 (When Writing Tests)
-
-4. **Test Driven Development**: `references/test-driven-development.md`
-   - Complete TDD methodology
-   - Red-Green-Refactor cycle
-   - When to read: When needing to understand TDD principles
-
-5. **Test Layering Strategy**: `references/test-layering-strategy.md`
-   - Unit/Integration/E2E test layering
-   - Test pyramid principles
-   - When to read: When planning test type distribution
-
-6. **Test Layering and Execution Strategy**: `references/test-layering-and-execution-strategy.md`
-   - @smoke/@critical/@full label details
-   - Test run strategy by phase
-   - Async vs sync boundaries
-   - When to read: When needing to understand test run strategy
-
-7. **Decoupling Techniques Cheatsheet**: `references/decoupling-techniques-cheatsheet.md`
-   - Mock/Stub/Fake techniques
-   - Dependency injection patterns
-   - When to read: When needing to isolate external dependencies
-
-8. **Async System Test Strategy**: `references/async-system-test-strategy.md`
-   - Async code testing techniques
-   - Event-driven system testing
-   - When to read: When testing async functionality
-
-9. **Verification Template and Structure**: `references/verification-template-and-structure.md`
-   - Complete verification.md template
-   - Status field permissions
-   - AC coverage matrix structure
-   - When to read: When creating verification.md
-
-10. **Change Verification and Traceability Template**: `references/9-change-verification-traceability-template.md`
-    - Traceability matrix template
-    - Boundary condition checklist
-    - When to read: When needing complete template reference
-
-### Must Read for Phase 2 (When Auditing Evidence)
-
-11. **Phase 2 Evidence Audit Checklist**: `references/phase2-evidence-audit-checklist.md`
-    - Complete evidence audit steps
-    - When to sample rerun
-    - How to check off AC matrix
-    - When to read: Immediately upon entering Phase 2
-
----
+- Allowed: `tests/**`, `verification.md`, evidence logs.
+- Prohibited: implementation changes, editing `tasks.md`.
 
-## Core Workflow
-
-### Phase 1: Red Baseline (Write Tests)
-
-1. **Read design documents**:
-   ```bash
-   # Read design.md and ACs
-   cat <change-root>/<change-id>/design.md
-   ```
-
-2. **Create verification.md**:
-   - Use `references/verification-template-and-structure.md`
-   - Establish AC coverage matrix
-   - Set Status = `Draft`
-
-3. **Write tests**:
-   - Strictly follow `references/absolute-rules-and-constraints.md`
-   - Reference `references/test-code-prompt.md`
-   - At least one test per AC
-
-4. **Run tests to produce Red baseline**:
-   ```bash
-   # Only run newly written tests (incremental)
-   npm test -- --grep "AC-001|AC-002"
-
-   # Save failure evidence
-   npm test 2>&1 | tee <change-root>/<change-id>/evidence/red-baseline/test-$(date +%Y%m%d-%H%M%S).log
-   ```
-
-5. **Update verification.md**:
-   - Set Status = `Ready`
-   - Record Red baseline evidence path
-
-6. **Check for deviations**:
-   - If design gaps found, record to `deviation-log.md`
-   - Reference `~/.claude/skills/_shared/references/deviation-detection-routing-protocol.md`
-
-### Phase 2: Green Verification (Audit Evidence)
-
-**Complete steps detailed in**: `references/phase2-evidence-audit-checklist.md`
-
-Brief workflow:
-1. Check `@full` tests have passed
-2. Audit `evidence/green-final/` directory
-3. Verify commit hash consistency
-4. Audit test logs
-5. Verify AC coverage
-6. Optional sampling rerun
-7. Check off AC matrix
-8. Set Status = `Verified`
-
----
-
-## Key Constraints
-
-### Role Boundaries
-
-| Allowed | Prohibited |
-|---------|------------|
-| Write tests in `tests/**` | ❌ Modify `src/**` code |
-| Check off AC matrix (Phase 2) | ❌ Modify `tasks.md` |
-| Set verification.md Status to Ready/Verified | ❌ Set Status to Done (Reviewer only) |
-| Record deviations to `deviation-log.md` | ❌ Modify design.md directly |
-| Run incremental tests (Phase 1) | ❌ Skip Red baseline |
-| Audit evidence (Phase 2) | ❌ Check off AC matrix before @full passes |
-
-### Code Quality Constraints
-
-#### Test Isolation Requirements
-
-- [ ] Each test must run independently, not dependent on execution order of other tests
-- [ ] Integration tests must have `beforeEach`/`afterEach` cleanup
-- [ ] Shared mutable state is prohibited
-- [ ] Tests must clean up created files/data after completion
-
-#### Test Stability Requirements
-
-- [ ] Committing `test.only` / `it.only` / `describe.only` is prohibited
-- [ ] Flaky tests must be marked and fixed within a deadline (no more than 1 week)
-- [ ] Test timeouts must be reasonably set (unit tests < 5s, integration tests < 30s)
-- [ ] External network dependencies are prohibited (mock all external calls)
-
----
-
-## Output Management
-
-Prevent large outputs from polluting context:
-
-| Scenario | Handling |
-|----------|----------|
-| Test output > 50 lines | Keep only first and last 10 lines + failure summary |
-| Red baseline logs | Write to `evidence/red-baseline/`, only reference path in dialogue |
-| Green evidence logs | Write to `evidence/green-final/`, only reference path in dialogue |
-| Large test case lists | Use table summary, do not paste item by item |
-
----
-
-## Evidence Path Convention
-
-**Green evidence must be saved**:
-```
-<change-root>/<change-id>/evidence/green-final/
-```
-
-**Correct path examples**:
-```bash
-# Dev-Playbooks default path
-dev-playbooks/changes/<change-id>/evidence/green-final/test-$(date +%Y%m%d-%H%M%S).log
-
-# Using the script
-devbooks change-evidence <change-id> --label green-final -- npm test
-```
-
----
-
-## Deviation Detection and Persistence
-
-**Reference**: `~/.claude/skills/_shared/references/deviation-detection-routing-protocol.md`
-
-During test writing, **must immediately** write to `deviation-log.md` in these situations:
-
-| Situation | Type | Example |
-|-----------|------|---------|
-| Found boundary case not covered by design.md | DESIGN_GAP | Concurrent write scenario |
-| Found additional constraints needed | CONSTRAINT_CHANGE | Need to add parameter validation |
-| Found interface adjustment needed | API_CHANGE | Need to add return field |
-| Found configuration change needed | CONSTRAINT_CHANGE | Need new config parameter |
-
----
-
-## Context Awareness
-
-This Skill automatically detects context before execution to ensure role isolation and prerequisite satisfaction.
-
-Detection rules reference: `~/.claude/skills/_shared/context-detection-template.md`
-
-### Modes Supported by This Skill
-
-| Mode | Trigger Condition | Behavior |
-|------|-------------------|----------|
-| **Initial Writing** | `verification.md` does not exist | Create complete acceptance test suite |
-| **Supplementary Tests** | `verification.md` exists but has `[TODO]` | Add missing test cases |
-| **Red Baseline Verification** | Tests exist, need to confirm Red status | Run tests and record failure logs |
-| **Evidence Audit** | User says "verify/check off" and @full passes | Audit evidence and check off AC matrix |
-
----
-
-## Completion Status and Next Step Routing
-
-### Phase 1 Completion Status
-
-| Code | Status | Determination Criteria | Next Step |
-|:----:|--------|------------------------|-----------|
-| ✅ | PHASE1_COMPLETED | Red baseline produced, no deviations | Switch to `[CODER]` mode |
-| ⚠️ | 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 |
-
-### Phase 2 Completion Status
-
-| Code | Status | Determination Criteria | Next Step |
-|:----:|--------|------------------------|-----------|
-| ✅ | PHASE2_VERIFIED | Evidence audit passed, AC matrix checked | `devbooks-reviewer` |
-| ⏳ | PHASE2_WAITING | @full tests still running | Wait for CI to complete |
-| ❌ | PHASE2_FAILED | @full tests not passing | Notify Coder to fix |
-| 🔄 | PHASE2_HANDOFF | Found issues with tests themselves | Fix tests then re-verify |
-
-### Routing Output Template (Must Use)
-
-```markdown
-## Completion Status
-
-**Phase**: Phase 1 (Red Baseline) / Phase 2 (Green Verification)
-
-**Status**: ✅ PHASE1_COMPLETED / ✅ PHASE2_VERIFIED / ...
-
-**Red Baseline**: Produced / Not completed (Phase 1 only)
-
-**@full Tests**: Passed / Running / Failed (Phase 2 only)
-
-**Evidence Audit**: Completed / Pending (Phase 2 only)
-
-**AC Matrix**: Checked N/M / Not checked (Phase 2 only)
-
-**Deviation Records**: Has N pending / None
-
-## Next Step
-
-**Recommended**: Switch to `[CODER]` mode / `devbooks-xxx skill`
-
-**Reason**: [specific reason]
-```
-
----
-
-## MCP Enhancement
-
-This Skill does not depend on MCP services, no runtime detection required.
+## Prerequisites: Configuration Discovery
 
-MCP enhancement rules reference: `~/.claude/skills/_shared/mcp-enhancement-template.md`
+Before execution, you **must** search for configuration in the following order (stop when found):
+1. `.devbooks/config.yaml` (if exists) -> Parse and use its mappings
+2. `dev-playbooks/project.md` (if exists) -> Dev-Playbooks protocol, use default mappings
+3. `project.md` (if exists) -> Template protocol, use default mappings
+4. If still undetermined -> **Stop and ask the user**
+
+If the configuration specifies `agents_doc` (rules document), you **must read that document first** before performing any operations.
+
+## Minimal Workflow
+
+### Phase 1: Red Baseline
+1. Read `design.md` and relevant specs.
+2. Create or update `verification.md` with an AC coverage matrix.
+3. Write tests under `tests/**`.
+4. Run incremental tests and save Red baseline logs under `evidence/red-baseline/`.
+5. Set verification status to `Ready` and reference the Red evidence path.
+
+### Phase 2: Green Verification
+1. Confirm Green evidence exists under `evidence/green-final/`.
+2. Audit logs and consistency of commit hashes (if applicable).
+3. Optionally rerun a small sampling set when evidence is insufficient.
+4. Check off the AC matrix and set status to `Verified`.
+
+## References
+
+Required:
+- `~/.claude/skills/_shared/references/ai-behavior-guidelines.md`
+- `references/absolute-rules-and-constraints.md`
+- `references/test-code-prompt.md`
+- `references/verification-template-and-structure.md`
+- `references/phase2-evidence-audit-checklist.md`
+
+As needed:
+- `references/test-driven-development.md`
+- `references/test-layering-strategy.md`
+- `references/test-layering-and-execution-strategy.md`
+- `references/decoupling-techniques-cheatsheet.md`
+- `references/async-system-test-strategy.md`
+- `references/9-change-verification-traceability-template.md`
+- `~/.claude/skills/_shared/references/deviation-detection-routing-protocol.md`

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

@@ -244,12 +244,22 @@ Detection Results:
 
 ---
 
-## MCP Enhancement
 
-This Skill does not depend on MCP services and requires no runtime detection.
+## Progressive Disclosure
+### Base (Required)
+Goal: Clarify this Skill's core outputs and usage scope.
+Inputs: User goals, existing documents, change package context, or project path.
+Outputs: Executable artifacts, next-step guidance, or recorded paths.
+Boundaries: Does not replace other roles; does not touch `tests/`.
+Evidence: Reference output paths or execution records.
 
-MCP enhancement rules reference: `skills/_shared/mcp-enhancement-template-mcp-enhancement.md`
+### Advanced (Optional)
+Use when you need to refine strategy, boundaries, or risk notes.
 
----
+### Extended (Optional)
+Use when you need to coordinate with external systems or optional tools.
 
-*This Skill document follows the devbooks-* specification.*
+## Recommended MCP Capability Types
+- Code search (code-search)
+- Reference tracking (reference-tracking)
+- Impact analysis (impact-analysis)