dev-playbooks 1.0.0

package/skills/devbooks-router/SKILL.md

@@ -0,0 +1,346 @@
+---
+name: devbooks-router
+description: "devbooks-router: DevBooks workflow routing and next-step recommendations. Routes user requests (proposal/design/spec/plan/test/implement/review/archive, or DevBooks proposal/apply/archive) to appropriate devbooks-* Skills, providing artifact destinations and shortest closed-loop paths. Use when user asks 'what's next/route to appropriate skill/run DevBooks closed-loop' etc."
+tools:
+  - Glob
+  - Grep
+  - Read
+  - Bash
+  - mcp__ckb__getStatus
+---
+
+# DevBooks: Workflow Router
+
+## Prerequisites: Configuration Discovery (Protocol-Agnostic)
+
+- `<truth-root>`: Current truth directory root
+- `<change-root>`: Change package directory root
+
+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) → DevBooks 2.0 protocol, use default mappings
+4. `project.md` (if exists) → Template protocol, use default mappings
+5. If still undetermined → **Stop and ask user**
+
+**Key Constraints**:
+- If configuration specifies `agents_doc` (rules document), **you must read that document first** before executing any operations
+- Do not guess directory roots
+- Do not skip reading the rules document
+
+## Prerequisites: Graph Index Health Check (Automatic)
+
+**Automatically executed before routing**, checks CKB graph index status:
+
+1. Call `mcp__ckb__getStatus` to check SCIP backend
+2. If `backends.scip.healthy = false`:
+   - Prompt user: "Code graph index not activated detected, impact analysis/call graph and other graph-based capabilities unavailable"
+   - Ask if they want to generate index now (approximately 1-5 minutes)
+   - If user agrees, execute `devbooks-index-bootstrap` workflow
+   - If user declines, continue routing but mark "graph capabilities degraded"
+
+3. If `backends.scip.healthy = true`:
+   - Pass silently, continue routing
+
+**Check Script** (for reference):
+```bash
+# Detect language and generate index
+if [ -f "tsconfig.json" ]; then
+  scip-typescript index --output index.scip
+elif [ -f "pyproject.toml" ]; then
+  scip-python index . --output index.scip
+elif [ -f "go.mod" ]; then
+  scip-go --output index.scip
+fi
+```
+
+**Degraded Mode Notes**:
+- Without index, `devbooks-impact-analysis` degrades to Grep text search (reduced accuracy)
+- Without index, `devbooks-code-review` cannot obtain call graph context
+- Recommend completing index generation before the Apply phase
+
+## Your Task
+
+Map the user's natural language request to:
+1) Current phase (proposal / apply / review / archive)
+2) Required artifacts for this change (proposal/design/tasks/verification) and optional artifacts (spec deltas/contract/c4/evidence)
+3) Which `devbooks-*` Skill(s) to use next
+4) File path for each artifact
+
+## Output Requirements (Mandatory)
+
+1) **Ask 2 minimum key questions first** (skip if context already provides answers):
+   - What is the `<change-id>`?
+   - What are the final values of `<truth-root>` / `<change-root>` for this project?
+2) Provide "next-step routing results" (3-6 items):
+   - Each item includes: Skill to use + artifact path + why it's needed
+3) Only enter the corresponding Skill's output mode if the user explicitly asks you to "start producing file content directly."
+
+---
+
+## Impact Profile Parsing (AC-003 / AC-012)
+
+When `proposal.md` exists, Router **should automatically parse** the Impact section to generate a more precise execution plan.
+
+### Impact Profile Structure
+
+```yaml
+impact_profile:
+  external_api: true/false       # External API changes
+  architecture_boundary: true/false  # Architecture boundary changes
+  data_model: true/false         # Data model changes
+  cross_repo: true/false         # Cross-repository impact
+  risk_level: high/medium/low    # Risk level
+  affected_modules:              # List of affected modules
+    - name: <module-path>
+      type: add/modify/delete
+      files: <count>
+```
+
+### Parsing Flow
+
+1. Check if `proposal.md` exists
+2. If exists, find `## Impact` section
+3. Extract `impact_profile:` YAML block
+4. Validate required fields: `external_api`, `risk_level`, `affected_modules`
+
+### Routing Enhancement Based on Impact Profile
+
+| Impact Field | Value | Auto-Append Skill |
+|--------------|-------|-------------------|
+| `external_api: true` | - | `devbooks-spec-contract` |
+| `architecture_boundary: true` | - | `devbooks-c4-map` |
+| `cross_repo: true` | - | `devbooks-federation` |
+| `risk_level: high` | - | `devbooks-proposal-debate-workflow` |
+| `affected_modules` count > 5 | - | `devbooks-impact-analysis` (deep analysis) |
+
+### Execution Plan Output Format
+
+```markdown
+## Execution Plan (Based on Impact Profile)
+
+### Must Execute
+1. `/devbooks:proposal` → proposal.md (proposal exists, skip)
+2. `/devbooks:design` → design.md (required)
+3. `/devbooks:plan` → tasks.md (required)
+
+### Recommended (Based on Impact Analysis)
+4. `/devbooks:spec` → specs/** (detected external_api: true)
+5. `/devbooks:c4` → architecture/c4.md (detected architecture_boundary: true)
+
+### Optional
+6. `/devbooks:impact` → Deep impact analysis (affected_modules > 5)
+```
+
+### Parse Failure Handling (AC-012)
+
+**When Impact Profile is missing**:
+
+```
+Warning: Impact profile not found in proposal.md.
+
+Missing items:
+- Impact section does not exist
+- Or impact_profile YAML block is missing
+
+Suggested actions:
+1. Run `/devbooks:impact` to generate impact analysis
+2. Or use direct command `/devbooks:<skill>` directly
+
+Direct command list:
+- /devbooks:design → Design document
+- /devbooks:plan → Implementation plan
+- /devbooks:spec → Specification definition
+```
+
+**When YAML parsing fails**:
+
+```
+Warning: Impact profile parsing failed.
+
+Error: <specific error message>
+
+Suggested actions:
+1. Check impact_profile YAML format in proposal.md
+2. Or use direct command `/devbooks:<skill>` to bypass Router
+```
+
+---
+
+## Routing Rules (Quality-First Default)
+
+### A) Proposal (Proposal Phase)
+
+Trigger signals: User says "proposal/why change/scope/risk/code smell refactoring/should we do this/don't write code yet" etc.
+
+Default routing:
+- `devbooks-proposal-author` → `(<change-root>/<change-id>/proposal.md)` (required)
+- `devbooks-design-doc` → `(<change-root>/<change-id>/design.md)` (required for non-trivial changes; only write What/Constraints + AC-xxx)
+- `devbooks-implementation-plan` → `(<change-root>/<change-id>/tasks.md)` (required; derive only from design)
+
+Append as needed (add only when conditions are met):
+- **Cross-module/unclear impact**: `devbooks-impact-analysis` (recommend writing back to proposal Impact)
+- **Obvious risks/controversies/trade-offs**: `devbooks-proposal-debate-workflow` (Author/Challenger/Judge, write back to Decision Log after debate)
+- **External behavior/contract/data invariant changes**: `devbooks-spec-contract` → `(<change-root>/<change-id>/specs/**)` + `design.md` Contract section
+  - If you need "deterministic spec delta file creation/avoid path errors": `change-spec-delta-scaffold.sh <change-id> <capability> ...`
+- **Module boundary/dependency direction/architecture shape changes**: `devbooks-c4-map` → `(<truth-root>/architecture/c4.md)`
+
+Hard constraint reminders:
+- Proposal phase prohibits writing implementation code; implementation happens in apply phase with tests/gates as completion criteria.
+- If you need "deterministic scaffold creation/avoid missing files": prefer running `devbooks-delivery-workflow` scripts
+  - `change-scaffold.sh <change-id> ...`
+  - `change-check.sh <change-id> --mode proposal ...`
+
+### B) Apply (Implementation Phase: Test Owner / Coder)
+
+Trigger signals: User says "start implementation/run tests/fix failures/follow tasks/make all gates green" etc.
+
+Default routing (mandatory role separation):
+- Test Owner (separate conversation/separate instance): `devbooks-test-owner`
+  - Artifacts: `(<change-root>/<change-id>/verification.md)` + `tests/**`
+  - First run to produce **Red** baseline, and record evidence (e.g., `(<change-root>/<change-id>/evidence/**)`)
+- Coder (separate conversation/separate instance): `devbooks-coder`
+  - Input: `tasks.md` + test errors + codebase
+  - Prohibited from modifying `tests/**`
+
+Apply phase deterministic checks (recommended):
+- Test Owner: `change-check.sh <change-id> --mode apply --role test-owner ...`
+- Test Owner (evidence recording): `change-evidence.sh <change-id> --label red-baseline -- <test-command>`
+- Coder: `change-check.sh <change-id> --mode apply --role coder ...` (additionally checks that `tests/**` is unmodified in git diff)
+
+LSC (Large-Scale Codemods) recommendations:
+- First use `change-codemod-scaffold.sh <change-id> --name <codemod-name> ...` to generate codemod script scaffold, then use script for batch changes and record evidence
+
+### C) Review (Review Phase)
+
+Trigger signals: User says "review/code smells/maintainability/dependency risks/consistency" etc.
+
+Default routing:
+- `devbooks-code-review` (output actionable suggestions; do not change business conclusions or tests)
+
+### D) Archive (Archive Phase)
+
+Trigger signals: User says "archive/merge specs/close out/wrap up" etc.
+
+Default routing:
+- If spec deltas were produced this time: `devbooks-spec-gardener` (prune `<truth-root>/**` before archive merge)
+- If design decisions need to be written back: `devbooks-design-backport` (as needed)
+
+Pre-archive deterministic checks (recommended):
+- `change-check.sh <change-id> --mode strict ...` (requires: proposal Approved, tasks all checked, trace matrix has no TODOs, structural gate decisions filled in)
+
+### E) Prototype (Prototype Mode)
+
+> Source: "The Mythical Man-Month" Chapter 11 "Plan to Throw One Away" — "The first system built is never suitable for use...plan to throw one away"
+
+Trigger signals: User says "prototype first/quick validation/spike/--prototype/throwaway prototype/Plan to Throw One Away" etc.
+
+**Prototype mode applicable scenarios**:
+- Technical approach uncertain, need quick feasibility validation
+- First time building this type of feature, expect to rewrite
+- Need to explore actual behavior of APIs/libraries/frameworks
+
+**Default routing (prototype track constraints)**:
+
+1. Create prototype scaffold:
+   - `change-scaffold.sh <change-id> --prototype ...`
+   - Artifacts: `(<change-root>/<change-id>/prototype/)`
+
+2. Test Owner (separate conversation) uses `devbooks-test-owner --prototype`:
+   - Artifacts: `(<change-root>/<change-id>/prototype/characterization/)`
+   - Generate **characterization tests** (record actual behavior) rather than acceptance tests
+   - **No Red baseline required** — characterization tests assert "current state"
+
+3. Coder (separate conversation) uses `devbooks-coder --prototype`:
+   - Output path: `(<change-root>/<change-id>/prototype/src/)`
+   - Allowed to bypass lint/complexity thresholds
+   - **Prohibited from landing directly to repository `src/`**
+
+**Hard constraints (must follow)**:
+- Prototype code and production code are **physically isolated** (different directories)
+- Test Owner and Coder must still have **separate conversations/instances** (role separation unchanged)
+- Promoting prototype to production requires **explicit trigger** `prototype-promote.sh <change-id>`
+
+**Prerequisites for promoting prototype to production**:
+1. Create production-grade `design.md` (distill What/Constraints/AC-xxx from prototype learnings)
+2. Test Owner produces acceptance tests `verification.md` (replacing characterization tests)
+3. Complete the promotion checklist in `prototype/PROTOTYPE.md`
+4. Run `prototype-promote.sh <change-id>` and pass all gates
+
+**Prototype discard flow**:
+1. Record key insights learned to `proposal.md` Decision Log
+2. Delete `prototype/` directory
+
+## DevBooks Command Adaptation
+
+DevBooks uses `/devbooks:proposal`, `/devbooks:apply`, `/devbooks:archive` as entry points.
+Route according to A/B/C/D above, artifact paths follow `<truth-root>/<change-root>` mappings in project signposts.
+
+---
+
+## Context Awareness
+
+This Skill automatically detects context before execution, selecting appropriate routing strategy.
+
+Detection rules reference: `skills/_shared/context-detection-template.md`
+
+### Detection Flow
+
+1. Detect if change package exists
+2. Detect existing artifacts (proposal/design/tasks/verification)
+3. Infer current phase (proposal/apply/archive)
+4. Select default routing based on phase
+
+### Modes Supported by This Skill
+
+| Mode | Trigger Condition | Behavior |
+|------|-------------------|----------|
+| **New Change** | Change package doesn't exist or is empty | Route to proposal phase, suggest creating proposal.md |
+| **In Progress** | Change package exists, has partial artifacts | Recommend next step based on missing artifacts |
+| **Ready to Archive** | Gates passed, `evidence/green-final/` exists | Route to archive phase |
+
+### Detection Output Example
+
+```
+Detection results:
+- Change package status: exists
+- Existing artifacts: proposal.md ✓, design.md ✓, tasks.md ✓, verification.md ✗
+- Current phase: apply
+- Suggested routing: devbooks-test-owner (establish Red baseline first)
+```
+
+---
+
+## MCP Enhancement
+
+This Skill supports MCP runtime enhancement, automatically detecting and enabling advanced features.
+
+MCP enhancement rules reference: `skills/_shared/mcp-enhancement-template.md`
+
+### Required MCP Services
+
+| Service | Purpose | Timeout |
+|---------|---------|---------|
+| `mcp__ckb__getStatus` | Detect CKB index availability | 2s |
+
+### Detection Flow
+
+1. Call `mcp__ckb__getStatus` (2s timeout)
+2. If CKB available → Mark "graph capabilities activated" in routing suggestions
+3. If timeout or failure → Mark "graph capabilities degraded" in routing suggestions, recommend running /devbooks:index
+
+### Enhanced Mode vs Basic Mode
+
+| Feature | Enhanced Mode | Basic Mode |
+|---------|---------------|------------|
+| Impact analysis recommendation | Use CKB precise analysis | Use Grep text search |
+| Code navigation | Symbol-level navigation available | File-level search |
+| Hotspot detection | CKB real-time analysis | Unavailable |
+
+### Degradation Notice
+
+When MCP is unavailable, output the following notice:
+
+```
+Warning: CKB index not activated, graph capabilities (impact analysis, call graph, etc.) will be degraded.
+Recommend running /devbooks:index to generate index for full functionality.
+```

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

@@ -0,0 +1,191 @@
+---
+name: devbooks-spec-contract
+description: devbooks-spec-contract: Define external behavior specifications and contracts (Requirements/Scenarios/API/Schema/compatibility strategies/migrations), and suggest or generate contract tests. Combines the functionality of the original spec-delta and contract-data. Use when the user says "write spec/specification/contract/OpenAPI/Schema/compatibility strategy/contract tests" etc.
+tools:
+  - Glob
+  - Grep
+  - Read
+  - Write
+  - Edit
+  - Bash
+---
+
+# DevBooks: Spec & Contract
+
+> This skill combines the functionality of the original `devbooks-spec-delta` and `devbooks-contract-data`, reducing decision fatigue.
+
+## Prerequisites: Configuration Discovery (Protocol-Agnostic)
+
+- `<truth-root>`: Current truth directory root
+- `<change-root>`: Change package directory root
+
+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) -> DevBooks 2.0 protocol, use default mappings
+4. `project.md` (if exists) -> Template protocol, use default mappings
+5. If still unable to determine -> **Stop and ask the user**
+
+**Key Constraints**:
+- If `agents_doc` (rules document) is specified in the configuration, **you must read that document first** before executing any operations
+- Do not guess directory roots
+- Do not skip reading the rules document
+
+---
+
+## Artifact Destinations
+
+| Artifact Type | Destination Path |
+|---------------|------------------|
+| Spec delta | `<change-root>/<change-id>/specs/<capability>/spec.md` |
+| Contract plan | `<change-root>/<change-id>/design.md` (Contract section) or standalone `contract-plan.md` |
+| Contract Test IDs | Written to traceability matrix in `verification.md` |
+| Implicit change report | `<change-root>/<change-id>/evidence/implicit-changes.json` |
+
+---
+
+## Use Case Determination
+
+| Scenario | What to Do |
+|----------|------------|
+| Behavior changes only (no API/Schema) | Output only spec.md (Requirements/Scenarios) |
+| API/Schema/event changes | Output spec.md + contract plan + Contract Test IDs |
+| Compatibility risks | Additionally output compatibility strategy, deprecation policy, migration plan |
+| Dependency/configuration/build changes | Run implicit change detection |
+
+---
+
+## Execution Method
+
+### Standard Process
+
+1) First read and follow: `_shared/references/universal-gating-protocol.md`
+2) Specification part: Output Requirements/Scenarios per `references/spec-change-prompt.md`
+3) Contract part: Output contract plan per `references/contract-and-data-definition-prompt.md`
+4) **Implicit change detection (as needed)**: `references/implicit-change-detection-prompt.md`
+
+### Output Structure (Single Output)
+
+```markdown
+## Spec Delta
+
+### Requirements
+- REQ-XXX-001: <requirement description>
+
+### Scenarios
+- SC-001: <scenario description>
+  - Given: ...
+  - When: ...
+  - Then: ...
+
+---
+
+## Contract Plan
+
+### API Changes
+- New/modified endpoint: `POST /api/v1/orders`
+- OpenAPI diff location: `contracts/openapi/orders.yaml`
+
+### Compatibility Strategy
+- Backward compatible: Yes/No
+- Deprecation policy: <if applicable>
+- Migration plan: <if applicable>
+
+### Contract Test IDs
+| Test ID | Type | Covered Scenario |
+|---------|------|------------------|
+| CT-001 | schema | REQ-XXX-001 |
+| CT-002 | behavior | SC-001 |
+```
+
+---
+
+## Scripts
+
+- Implicit change detection: `scripts/implicit-change-detect.sh <change-id> [--base <commit>] [--project-root <dir>] [--change-root <dir>]`
+
+---
+
+## Context Awareness
+
+This Skill automatically detects context before execution and selects the appropriate operating mode.
+
+Detection rules reference: `skills/_shared/context-detection-template.md`
+
+### Detection Process
+
+1. Detect whether `<change-root>/<change-id>/specs/` exists
+2. If exists, assess completeness (whether there are placeholders, whether REQs have Scenarios)
+3. Select operating mode based on detection results
+
+### Supported Modes for This Skill
+
+| Mode | Trigger Condition | Behavior |
+|------|-------------------|----------|
+| **Create from scratch** | `specs/` directory doesn't exist or is empty | Create complete spec document structure, including Requirements/Scenarios |
+| **Gap-filling mode** | `specs/` exists but incomplete (has `[TODO]`, REQ missing Scenario) | Fill in missing Requirements/Scenarios, preserve existing content |
+| **Sync mode** | `specs/` complete, needs synchronization with implementation | Check consistency between implementation and specs, output diff report |
+
+### Detection Output Example
+
+```
+Detection Results:
+- Artifact existence: specs/ exists
+- Completeness: Incomplete (missing: REQ-002 has no Scenario)
+- Current phase: apply
+- Operating mode: Gap-filling mode
+```
+
+---
+
+## Implicit Change Detection (Extended Feature)
+
+> Source: "The Mythical Man-Month" Chapter 7 "The Tower of Babel" - "Teams slowly modify the functions of their own programs, implicitly changing the conventions"
+
+Implicit changes = changes that are not explicitly declared but alter system behavior.
+
+**Detection Scope**:
+- Dependency changes (package.json / requirements.txt / go.mod etc.)
+- Configuration changes (*.env / *.config.* / *.yaml etc.)
+- Build changes (tsconfig.json / Dockerfile / CI configs etc.)
+
+**Integration with change-check.sh**:
+- Automatically checks implicit change reports in `apply` / `archive` / `strict` modes
+- High-risk implicit changes must be declared in `design.md`
+
+---
+
+## MCP Enhancement
+
+This Skill supports MCP runtime enhancement, automatically detecting and enabling advanced features.
+
+MCP enhancement rules reference: `skills/_shared/mcp-enhancement-template.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 running /devbooks:index to generate the index.
+```