dev-playbooks 2.2.0 → 2.3.0

package/skills/devbooks-brownfield-bootstrap/SKILL.md

@@ -61,7 +61,8 @@ Generate in `<truth-root>/_meta/`:
 |----------|------|-------------|
 | Project profile | `_meta/project-profile.md` | Detailed technical profile with three-layer architecture |
 | Glossary | `_meta/glossary.md` | Unified language table (optional but recommended) |
-| Domain concepts | `_meta/key-concepts.md` | Concepts extracted by CKB (enhanced mode) |
+| Documentation maintenance metadata | `_meta/docs-maintenance.md` | Documentation style and maintenance configuration |
+| Domain concepts | `_meta/key-concepts.md` | Concept extraction based on code semantics (optional) |
 
 ### 3. Architecture Analysis Artifacts
 
@@ -69,9 +70,9 @@ Generate in `<truth-root>/architecture/`:
 
 | Artifact | Path | Data Source |
 |----------|------|-------------|
-| **C4 Architecture Map** | `architecture/c4.md` | Comprehensive analysis + CKB (enhanced mode) |
-| Module dependency graph | `architecture/module-graph.md` | `mcp__ckb__getArchitecture` |
-| Technical debt hotspots | `architecture/hotspots.md` | `mcp__ckb__getHotspots` |
+| **C4 Architecture Map** | `architecture/c4.md` | Comprehensive analysis (optionally with structured capability) |
+| Module dependency graph | `architecture/module-graph.md` | Structured dependency analysis (optional) |
+| Technical debt hotspots | `architecture/hotspots.md` | Change history + complexity analysis (optional) |
 | Layering constraints | `architecture/layering-constraints.md` | Code analysis (optional) |
 
 > **Design Decision**: C4 architecture map is now generated by brownfield-bootstrap during initialization. Subsequent architecture changes are recorded in design.md's Architecture Impact section and merged by archiver during archiving.
@@ -91,16 +92,16 @@ Generate in `<change-root>/<baseline-id>/`:
 
 ## COD Model Generation (Code Overview & Dependencies)
 
-Automatically generate project's "code map" during initialization (requires CKB MCP Server available, otherwise skip):
+Optionally generate the project's "code map" during initialization, based on available structured code analysis capability:
 
 ### Auto-generated Artifacts
 
 | Artifact | Path | Data Source |
 |----------|------|-------------|
 | **C4 Architecture Map** | `<truth-root>/architecture/c4.md` | Comprehensive analysis |
-| Module dependency graph | `<truth-root>/architecture/module-graph.md` | `mcp__ckb__getArchitecture` |
-| Technical debt hotspots | `<truth-root>/architecture/hotspots.md` | `mcp__ckb__getHotspots` |
-| Domain concepts | `<truth-root>/_meta/key-concepts.md` | `mcp__ckb__listKeyConcepts` |
+| Module dependency graph | `<truth-root>/architecture/module-graph.md` | Structured dependency analysis (optional) |
+| Technical debt hotspots | `<truth-root>/architecture/hotspots.md` | Change history + complexity analysis (optional) |
+| Domain concepts | `<truth-root>/_meta/key-concepts.md` | Code semantic concept extraction (optional) |
 | Project profile | `<truth-root>/_meta/project-profile.md` | Comprehensive analysis |
 
 ### C4 Architecture Map Generation Rules
@@ -162,23 +163,9 @@ Automatically distinguish:
 
 ### Execution Flow
 
-1) **Check Graph Index**: Call `mcp__ckb__getStatus`
-   - If SCIP available → Use graph-based analysis
-   - If unavailable → Prompt to generate index or use Git history analysis
-
-2) **Generate COD Artifacts**:
-   ```bash
-   # Get module architecture
-   mcp__ckb__getArchitecture(depth=2, includeExternalDeps=false)
-
-   # Get hotspots (last 30 days)
-   mcp__ckb__getHotspots(limit=20)
-
-   # Get domain concepts
-   mcp__ckb__listKeyConcepts(limit=12)
-   ```
-
-3) **Generate Project Profile**: Integrate above data + traditional analysis
+1) **Check available capability**: confirm structured code analysis capability (such as dependency or reference tracking).
+2) **Generate COD artifacts**: use available code search, reference tracking, and change history analysis to produce dependency graphs, hotspots, and concepts.
+3) **Generate project profile**: integrate the above data with traditional analysis.
 
 ## Reference Scaffolds and Templates
 
@@ -201,7 +188,7 @@ Detection rules reference: `skills/_shared/context-detection-template-context-de
 1. Detect if `<devbooks-root>/constitution.md` exists
 2. Detect if `<devbooks-root>/project.md` exists
 3. Detect if `<truth-root>/` is empty or basically empty
-4. Detect if CKB index is available
+4. Detect whether structured analysis capability is available
 5. Detect project scale and language stack
 
 ### Modes Supported by This Skill
@@ -212,8 +199,8 @@ Detection rules reference: `skills/_shared/context-detection-template-context-de
 | **Supplement Config** | constitution/project missing | Only supplement missing configuration files |
 | **Complete Init** | truth-root is empty | Generate all basic artifacts (profile/baseline/verification) |
 | **Incremental Init** | truth-root partially exists | Only supplement missing artifacts |
-| **Enhanced Mode** | CKB index available | Use graph analysis to generate more precise profile |
-| **Basic Mode** | CKB index unavailable | Use traditional analysis methods |
+| **Structured Analysis** | Structured capability available | Use dependency/reference tracking to refine the profile |
+| **Text Analysis** | Only text search available | Use traditional analysis methods |
 
 ### Detection Output Example
 
@@ -223,49 +210,29 @@ Detection Results:
 - constitution.md: Doesn't exist → Will create
 - project.md: Doesn't exist → Will create
 - truth-root: Empty
-- CKB index: Available
+- Structured capability: Available
 - Project scale: Medium (~50K LOC)
-- Running mode: Supplement Config + Complete Init + Enhanced Mode
+- Running mode: Supplement Config + Complete Init + Structured Analysis
 ```
 
 ---
 
-## 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`
-
-### Required MCP Services
 
-| Service | Purpose | Timeout |
-|---------|---------|---------|
-| `mcp__ckb__getStatus` | Detect CKB index availability | 2s |
-| `mcp__ckb__getArchitecture` | Get module dependency graph | 2s |
-| `mcp__ckb__getHotspots` | Get technical debt hotspots | 2s |
-| `mcp__ckb__listKeyConcepts` | Get domain concepts | 2s |
-| `mcp__ckb__getModuleOverview` | Get module overview | 2s |
+## 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.
 
-### Detection Flow
-
-1. Call `mcp__ckb__getStatus` (2s timeout)
-2. If CKB available → Use graph-based analysis to generate COD artifacts
-3. If timeout or failure → Degrade to traditional analysis (Git history + file statistics)
-
-### Enhanced Mode vs Basic Mode
-
-| Feature | Enhanced Mode | Basic Mode |
-|---------|---------------|------------|
-| Module dependency graph | CKB getArchitecture | Directory structure inference |
-| Technical debt hotspots | CKB getHotspots | Git log statistics |
-| Domain concepts | CKB listKeyConcepts | Naming analysis |
-| Boundary identification | Precise module boundaries | Directory conventions |
+### Advanced (Optional)
+Use when you need to refine strategy, boundaries, or risk notes.
 
-### Degradation Notice
+### Extended (Optional)
+Use when you need to coordinate with external systems or optional tools.
 
-When MCP is unavailable, output the following notice:
-
-```
-Warning: CKB unavailable, using traditional analysis methods to generate project profile.
-For more precise architecture analysis, manually generate SCIP index.
-```
+## Recommended MCP Capability Types
+- Code search (code-search)
+- Reference tracking (reference-tracking)
+- Impact analysis (impact-analysis)

package/skills/devbooks-coder/SKILL.md

@@ -12,256 +12,77 @@ allowed-tools:
 
 # DevBooks: Implementation Lead (Coder)
 
-## Quick Start
+## Progressive Disclosure
 
-My responsibilities:
-1. **Strictly implement functionality according to tasks.md**
-2. **Run fast-track tests** (@smoke + @critical)
-3. **Trigger @full tests** (CI async)
-4. **Prohibited from modifying tests/**
+### Base (Required)
+Goal: Implement only what is specified in `tasks.md` and produce Green evidence.
+Inputs: user goal, `tasks.md`, project codebase, change package context.
+Outputs: implementation changes, updated `tasks.md`, Green evidence logs under `evidence/green-final/`.
+Boundaries: do not modify `tests/**`; do not edit `verification.md` or the AC matrix.
+Evidence: reference gate outputs and log paths.
 
-## Workflow Position
+### Advanced (Optional)
+Use when you need: risk notes, minimal-diff planning, deviation recording.
 
-```
-proposal → design → [TEST-OWNER] → [CODER] → [TEST-OWNER] → code-review → archive
-                                      ↓              ↓
-                               Implement+fast-track  Evidence audit+check off
-                              (@smoke/@critical)     (no @full rerun)
-```
+### Extended (Optional)
+Use when you need: faster search/impact via optional MCP capabilities.
 
-## AI Era Optimization
+## Recommended MCP Capability Types
 
-| 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 |
-| Coder runs full tests and waits for results | Coder runs fast-track (`@smoke`/`@critical`), `@full` triggered async | Fast iteration |
-| Directly hand to Test Owner after completion | Status becomes `Implementation Done` after completion, wait for @full | Async doesn't block, archive syncs |
+- Code search (code-search)
+- Reference tracking (reference-tracking)
+- Impact analysis (impact-analysis)
 
----
-
-## Prerequisites: Configuration Discovery
-
-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
-3. `project.md` (if exists) → Template protocol
-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
-
----
-
-## 📚 Reference Documentation
-
-### Must Read (Read Immediately)
-
-1. **AI Behavior Guidelines**: `~/.claude/skills/_shared/references/ai-behavior-guidelines.md`
-   - Verifiability gating, structural quality gating, completeness gating
-   - Foundation rules for all skills
-
-2. **Code Implementation Prompt**: `references/code-implementation-prompt.md`
-   - Complete code implementation guide
-   - Strictly follow this prompt
-
-### Read as Needed
-
-3. **Test Execution Strategy**: `references/test-execution-strategy.md`
-   - @smoke/@critical/@full label details
-   - Async vs sync boundaries
-   - When to read: When needing to understand test run strategy
-
-4. **Completion Status and Routing**: `references/completion-status-and-routing.md`
-   - Completion status classification (MECE)
-   - Routing output template
-   - When to read: When outputting status upon task completion
-
-5. **Hotspot Awareness and Risk Assessment**: `references/hotspot-awareness-and-risk-assessment.md`
-   - MCP enhancement features
-   - Hotspot file warnings
-   - When to read: When needing risk assessment
-
-6. **Low Risk Modification Techniques**: `references/low-risk-modification-techniques.md`
-   - Safe refactoring techniques
-   - When to read: When needing refactoring
-
-7. **Coding Style Guidelines**: `references/coding-style-guidelines.md`
-   - Code style specifications
-   - When to read: When uncertain about code style
-
-8. **Logging Standard**: `references/logging-standard.md`
-   - Log levels and formats
-   - When to read: When needing to add logs
-
-9. **Error Code Standard**: `references/error-code-standard.md`
-   - Error code design
-   - When to read: When needing to define error codes
-
----
-
-## Core Workflow
-
-### 1. Resume from Checkpoint
-
-**Must** execute before each start:
-
-1. **Read progress**: Open `<change-root>/<change-id>/tasks.md`, identify checked `- [x]` tasks
-2. **Locate resume point**: Find first `- [ ]` after "last `[x]`"
-3. **Output confirmation**: Clearly inform user of current progress, e.g.:
-   ```
-   Detected T1-T6 completed (6/10), continuing from T7.
-   ```
-
-### 2. Real-time Progress Updates
-
-> **Core Principle**: Complete one task, check off one immediately. Don't wait until all complete to batch check.
-
-**Check-off Timing**:
-
-| Timing | Action |
-|--------|--------|
-| Code writing complete | Don't check yet |
-| Compilation passes | Don't check yet |
-| Related tests pass | **Check immediately** |
-| Multiple tasks complete together | Check one by one, don't batch |
-
-### 3. Implement Code
-
-Strictly follow `references/code-implementation-prompt.md`.
-
-### 4. Run Tests
-
-```bash
-# During development: frequently run @smoke
-npm test -- --grep "@smoke"
-
-# Before commit: run @critical
-npm test -- --grep "@smoke|@critical"
-
-# After commit: CI automatically runs @full (Coder doesn't wait)
-git push  # Trigger CI
-```
+## Role Isolation (Mandatory)
 
-### 5. Output Completion Status
+- Test Owner and Coder must be separate conversations/instances.
+- Do not switch roles within one conversation.
+- If tests or `verification.md` require changes, hand off to Test Owner.
 
-Reference `references/completion-status-and-routing.md`.
+## Core Responsibilities
 
----
-
-## Key Constraints
-
-### Role Boundaries
-
-| Allowed | Prohibited |
-|---------|------------|
-| Modify `src/**` code | ❌ Modify `tests/**` |
-| Check off `tasks.md` task items | ❌ Modify `verification.md` |
-| Record deviations to `deviation-log.md` | ❌ Check off AC coverage matrix |
-| Run fast-track tests (`@smoke`/`@critical`) | ❌ Set verification.md Status to Verified/Done |
-| Trigger `@full` tests (CI/background) | ❌ Wait for @full completion (can start next change) |
-
-### Code Quality Constraints
-
-#### Prohibited Patterns for Commit
-
-| Pattern | Detection Command | Reason |
-|---------|-------------------|--------|
-| `test.only` | `rg '\.only\s*\(' src/` | Skips other tests |
-| `console.log` | `rg 'console\.log' src/` | Debug code remnants |
-| `debugger` | `rg 'debugger' src/` | Debug breakpoint remnants |
-| `// TODO` without issue | `rg 'TODO(?!.*#\d+)' src/` | Untraceable todos |
-| `any` type | `rg ': any[^a-z]' src/` | Type safety holes |
-| `@ts-ignore` | `rg '@ts-ignore' src/` | Hides type errors |
-
-#### Pre-commit Checks Required
-
-```bash
-# 1. Compilation check (mandatory)
-npm run compile || exit 1
+1. Implement strictly according to `<change-root>/<change-id>/tasks.md`.
+2. Run the gate checks required by the change (tests/build/static checks).
+3. Save Green evidence to `<change-root>/<change-id>/evidence/green-final/`.
+4. Check off tasks only when relevant gates pass.
+5. Record discoveries that require design/spec updates to `deviation-log.md`.
 
-# 2. Lint check (mandatory)
-npm run lint || exit 1
+## Hard Boundaries
 
-# 3. Test check (mandatory)
-npm test || exit 1
-
-# 4. test.only check (mandatory)
-if rg -l '\.only\s*\(' tests/ src/**/test/; then
-  echo "error: found .only() in tests" >&2
-  exit 1
-fi
-
-# 5. Debug code check (mandatory)
-if rg -l 'console\.(log|debug)|debugger' src/ --type ts; then
-  echo "error: found debug statements" >&2
-  exit 1
-fi
-```
-
----
-
-## Output Management
-
-Prevent large outputs from polluting context:
-
-| Scenario | Handling |
-|----------|----------|
-| Command output > 50 lines | Keep only first and last 10 lines + middle summary |
-| Test output | Extract key failure info, don't paste full output in dialogue |
-| Log output | Write to disk at `<change-root>/<change-id>/evidence/`, only reference path in dialogue |
-| Large file contents | Reference path, don't inline |
-
----
+- Allowed: implementation code, `tasks.md`, `deviation-log.md`, evidence logs.
+- Prohibited: `tests/**`, edits to `verification.md`, checking off the AC matrix.
 
-## 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 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 implementation, **must immediately** write to `deviation-log.md` in these situations:
-
-| Situation | Type | Example |
-|-----------|------|---------|
-| Added functionality not in tasks.md | NEW_FEATURE | Added warmup() method |
-| Modified constraints in design.md | CONSTRAINT_CHANGE | Timeout changed to 60s |
-| Found boundary case not covered by design | DESIGN_GAP | Concurrent write scenario |
-| Public interface inconsistent with design | API_CHANGE | Parameter added |
-
----
-
-## Context Awareness
-
-Detection rules reference: `~/.claude/skills/_shared/context-detection-template.md`
-
-### Modes Supported by This Skill
-
-| Mode | Trigger Condition | Behavior |
-|------|-------------------|----------|
-| **Initial Implementation** | All tasks.md are `[ ]` | Start from MP1.1 |
-| **Resume from Checkpoint** | tasks.md has some `[x]` | Continue from first `[ ]` after last `[x]` |
-| **Gate Fixing** | Test failures need fixing | Prioritize failed items |
-
-### Prerequisite Checks
+## Prerequisites: Configuration Discovery
 
-- [ ] `tasks.md` exists
-- [ ] `verification.md` exists
-- [ ] Test Owner not executed in current session
-- [ ] `tests/**` has test files
+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
+
+1. Read `<change-root>/<change-id>/tasks.md` and resume from the first unchecked item.
+2. Implement tasks with a minimal diff.
+3. Run relevant gates; if any gate fails, fix implementation (not tests) and rerun.
+4. Write logs to `evidence/green-final/` and reference them in your output.
+5. Check off completed tasks; do not batch-check.
+6. If you find gaps in design/spec/tasks, write them to `deviation-log.md` and hand off.
+
+## References
+
+Required:
+- `~/.claude/skills/_shared/references/ai-behavior-guidelines.md`
+- `references/code-implementation-prompt.md`
+
+As needed:
+- `references/test-execution-strategy.md`
+- `references/completion-status-and-routing.md`
+- `references/hotspot-awareness-and-risk-assessment.md`
+- `references/low-risk-modification-techniques.md`
+- `references/coding-style-guidelines.md`
+- `references/logging-standard.md`
+- `references/error-code-standard.md`
+- `~/.claude/skills/_shared/references/deviation-detection-routing-protocol.md`

package/skills/devbooks-coder/references/completion-status-and-routing.md

@@ -4,9 +4,9 @@
 
 | Code | Status | Determination Criteria | Next Step |
 |:----:|--------|------------------------|-----------|
-| ✅ | IMPLEMENTATION_DONE | Fast-track tests green, @full triggered, no deviations | Switch to `[TEST-OWNER]` wait for @full |
+| ✅ | IMPLEMENTATION_DONE | Fast-track tests green, @full triggered, no deviations | Hand off to Test Owner (separate conversation) for Phase 2 evidence audit |
 | ⚠️ | IMPLEMENTATION_DONE_WITH_DEVIATION | Fast-track green, deviation-log has pending records | `devbooks-design-backport` |
-| 🔄 | HANDOFF | Found test issues needing modification | Switch to `[TEST-OWNER]` mode to fix tests |
+| 🔄 | HANDOFF | Found test issues needing modification | Hand off to Test Owner (separate conversation) to update tests |
 | ❌ | BLOCKED | Needs external input/decision | Record breakpoint, wait for user |
 | 💥 | FAILED | Fast-track tests not passing | Fix and retry |
 
@@ -17,7 +17,7 @@
    → Yes: IMPLEMENTATION_DONE_WITH_DEVIATION
 
 2. Check if need to modify tests/
-   → Yes: HANDOFF to [TEST-OWNER] mode
+   → Yes: HANDOFF to Test Owner (separate conversation)
 
 3. Check if fast-track tests (@smoke + @critical) all pass
    → No: FAILED
@@ -48,7 +48,7 @@ After completing coder, **must** output in this format:
 
 ## Next Step
 
-**Recommended**: Switch to `[TEST-OWNER]` mode wait for @full / `devbooks-xxx skill`
+**Recommended**: Hand off to Test Owner (new conversation/instance) for Phase 2 / wait for @full if needed
 
 **Reason**: [specific reason]
 
@@ -59,16 +59,16 @@ After completing coder, **must** output in this format:
 
 | My Status | Next Step | Reason |
 |-----------|-----------|--------|
-| IMPLEMENTATION_DONE | Switch to `[TEST-OWNER]` mode (wait @full) | Fast-track green, wait for @full to pass then audit evidence |
+| IMPLEMENTATION_DONE | Hand off to Test Owner (separate conversation) | Fast-track green; Test Owner audits evidence after @full passes |
 | IMPLEMENTATION_DONE_WITH_DEVIATION | `devbooks-design-backport` | Backport design first |
-| HANDOFF (test issues) | Switch to `[TEST-OWNER]` mode | Coder cannot modify tests |
+| HANDOFF (test issues) | Hand off to Test Owner (separate conversation) | Coder cannot modify tests |
 | BLOCKED | Wait for user | Record breakpoint area |
 | FAILED | Fix and retry | Analyze failure reason |
 
 ## Key Constraints
 
 - Coder **can never modify** `tests/**`
-- If test issues found, must switch to `[TEST-OWNER]` mode to handle
+- If test issues are found, hand off to Test Owner (separate conversation) to handle
 - If deviations exist, must design-backport first before continuing
 - **After Coder completion status is `Implementation Done`, must wait for @full to pass before entering Test Owner Phase 2**
-- **Mode switching replaces session isolation**: Use `[TEST-OWNER]` / `[CODER]` labels to switch modes
+- **Role isolation is mandatory**: do not switch roles within one conversation

package/skills/devbooks-convergence-audit/SKILL.md

@@ -392,3 +392,23 @@ This report uses "evidence first, distrust declarations" principle. All conclusi
 - Fake completion → Immediately revert status, re-verify
 - Suspicious items → Supplement evidence or re-run tests
 - Trustworthy items → Continue current process
+
+
+## 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.
+
+### 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.
+
+## Recommended MCP Capability Types
+- Code search (code-search)
+- Reference tracking (reference-tracking)
+- Impact analysis (impact-analysis)