dev-playbooks 2.4.0 → 2.5.0

package/bin/devbooks.js

@@ -103,8 +103,9 @@ const AI_TOOLS = [
     id: 'cursor',
     name: 'Cursor',
     description: 'Cursor AI IDE',
-    skillsSupport: SKILLS_SUPPORT.RULES,
+    skillsSupport: SKILLS_SUPPORT.FULL,
     slashDir: '.cursor/commands/devbooks',
+    skillsDir: '.cursor/skills',  // Project-level
     rulesDir: '.cursor/rules',
     instructionFile: null,
     available: true

package/package.json

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

package/skills/devbooks-coder/SKILL.md

@@ -14,75 +14,261 @@ allowed-tools:
 
 ## Progressive Disclosure
 
-### Base (Required)
+### Base Layer (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.
+Inputs: User goal, existing docs, change package context, or project path.
+Outputs: Executable artifacts, updated `tasks.md`, Green evidence logs under `evidence/green-final/`.
+Boundaries: Do not replace other roles' duties; do not modify `tests/**`.
+Evidence: Reference output artifact paths or execution logs.
 
-### Advanced (Optional)
-Use when you need: risk notes, minimal-diff planning, deviation recording.
+### Advanced Layer (Optional)
+Use when: You need to refine strategies, boundaries, or highlight risks.
 
-### Extended (Optional)
-Use when you need: faster search/impact via optional MCP capabilities.
+### Extended Layer (Optional)
+Use when: You need to collaborate with external systems or optional tools.
 
 ## Recommended MCP Capability Types
-
 - Code search (code-search)
 - Reference tracking (reference-tracking)
 - Impact analysis (impact-analysis)
 
-## Role Isolation (Mandatory)
-
-- 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.
+## Quick Start
 
-## Core Responsibilities
+My Responsibilities:
+1. **Strictly implement functionality according to tasks.md**
+2. **Run acceptance anchors in the verification plan** (tests/, static checks, build, etc.)
+3. **Save Green evidence** to the change package `evidence/green-final/`
+4. **Prohibited from modifying tests/** (If tests need changes, hand back to Test Owner)
 
-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`.
+## Role Isolation (Mandatory)
 
-## Hard Boundaries
+- Test Owner and Coder must be in separate conversations/instances.
+- This Skill executes only as Coder and does not switch to other roles.
 
-- Allowed: implementation code, `tasks.md`, `deviation-log.md`, evidence logs.
-- Prohibited: `tests/**`, edits to `verification.md`, checking off the AC matrix.
+---
 
 ## Prerequisites: Configuration Discovery
 
 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
+2. `dev-playbooks/project.md` (if exists) -> Dev-Playbooks protocol
+3. `project.md` (if exists) -> template protocol
 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.
+**Key Constraints**:
+- If the configuration specifies `agents_doc` (rules document), you **must read that document first** before performing any operations.
+- Do not guess the directory root.
+
+---
+
+## 📚 Reference Documents
+
+### Required (Read Immediately)
+
+1. **AI Behavior Guidelines**: `~/.claude/skills/_shared/references/ai-behavior-guidelines.md`
+   - Verifiability gatekeeping, structural quality gatekeeping, completeness gatekeeping
+   - Basic rules for all skills
+
+2. **Code Implementation Prompt**: `references/code-implementation-prompt.md`
+   - Complete code implementation guide
+   - Execute strictly according to this prompt
+
+### Read on Demand
+
+3. **Test Execution Strategy**: `references/test-execution-strategy.md`
+   - Details on @smoke/@critical/@full tags
+   - Async vs. Sync boundaries
+   - *When to read*: When you need to understand the test execution strategy
+
+4. **Completion Status and Routing**: `references/completion-status-and-routing.md`
+   - Completion status classification (MECE)
+   - Routing output templates
+   - *When to read*: When outputting status upon task completion
+
+5. **Hotspot Awareness and Risk Assessment**: `references/hotspot-awareness-and-risk-assessment.md`
+   - Hotspot file warnings
+   - *When to read*: When risk assessment is needed
+
+6. **Low Risk Modification Techniques**: `references/low-risk-modification-techniques.md`
+   - Safe refactoring techniques
+   - *When to read*: When refactoring is needed
+
+7. **Coding Style Guidelines**: `references/coding-style-guidelines.md`
+   - Code style specifications
+   - *When to read*: When unsure about code style
+
+8. **Logging Standard**: `references/logging-standard.md`
+   - Log levels and formats
+   - *When to read*: When logging needs to be added
+
+9. **Error Code Standard**: `references/error-code-standard.md`
+   - Error code design
+   - *When to read*: When error codes need to be defined
+
+---
+
+## Core Workflow
+
+### 1. Resume from Breakpoint
+
+Before starting, you **must** execute:
+
+1. **Read Progress**: Open `<change-root>/<change-id>/tasks.md`, identify checked `- [x]` tasks.
+2. **Locate Resume Point**: Find the first `- [ ]` after the "last `[x]`".
+3. **Output Confirmation**: Clearly inform the user of the current progress, for example:
+   ```
+   Detected T1-T6 completed (6/10), resuming from T7.
+   ```
+
+### 2. Real-time Progress Updates
+
+> **Core Principle**: Complete one task, check one box immediately. Do not wait until all are done to batch check.
+
+**Check-off Timing**:
+
+| Timing | Action |
+|--------|--------|
+| Code writing complete | Do not check yet |
+| Compilation passes | Do not check yet |
+| Relevant tests pass | **Check immediately** |
+| Multiple tasks complete together | Check one by one, do not batch |
+
+### 3. Implement Code
+
+Execute strictly according to `references/code-implementation-prompt.md`.
+
+### 4. Run Tests
+
+```bash
+# During development: run @smoke frequently
+npm test -- --grep "@smoke"
+
+# Before committing: run @critical
+npm test -- --grep "@smoke|@critical"
+
+# After commit: CI automatically runs @full (Coder does not wait)
+git push  # triggers CI
+```
+
+### 5. Output Completion Status
+
+Refer to `references/completion-status-and-routing.md`.
+
+---
+
+## Key Constraints
+
+### Role Boundaries
+
+| Allowed | Prohibited |
+|---------|------------|
+| Modify `src/**` code | ❌ Modify `tests/**` |
+| Check `tasks.md` items | ❌ Modify `verification.md` |
+| Record deviations to `deviation-log.md` | ❌ Check 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
+
+#### Forbidden Commit Patterns
+
+| Pattern | Detection Command | Reason |
+|---------|-------------------|--------|
+| `test.only` | `rg '\.only\s*\(' src/` | Skips other tests |
+| `console.log` | `rg 'console\.log' src/` | Debug code residue |
+| `debugger` | `rg 'debugger' src/` | Debug breakpoint residue |
+| `// TODO` without issue | `rg 'TODO(?!.*#\d+)' src/` | Untrackable todo |
+| `any` type | `rg ': any[^a-z]' src/` | Type safety hole |
+| `@ts-ignore` | `rg '@ts-ignore' src/` | Hides type errors |
+
+#### Pre-commit Mandatory Checks
+
+```bash
+# 1. Compilation Check (Mandatory)
+npm run compile || exit 1
+
+# 2. Lint Check (Mandatory)
+npm run lint || exit 1
+
+# 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 output from polluting context:
+
+| Scenario | Handling Method |
+|----------|-----------------|
+| Command output > 50 lines | Keep only first/last 10 lines + middle summary |
+| Test output | Extract key failure info, do not paste full log |
+| Log output | Save to disk at `<change-root>/<change-id>/evidence/`, quote path only |
+| Large file content | Quote path, do not inline |
+
+---
+
+## Evidence Path Convention
+
+**Green evidence must be saved to**:
+```
+<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 Recording
+
+**Reference**: `~/.claude/skills/_shared/references/deviation-detection-routing-protocol.md`
+
+During implementation, you **must immediately** write the following situations to `deviation-log.md`:
+
+| Situation | Type | Example |
+|-----------|------|---------|
+| Added feature not in tasks.md | NEW_FEATURE | Added warmup() method |
+| Changed constraint in design.md | CONSTRAINT_CHANGE | Timeout changed to 60s |
+| Found edge case not covered by design | DESIGN_GAP | Public interface inconsistent with design |
+| API Signature Change | API_CHANGE | Argument added |
+
+---
+
+## Context Awareness
 
-## Minimal Workflow
+Detection rules refer to: `~/.claude/skills/_shared/context-detection-template.md`
 
-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.
+### Modes Supported by This Skill
 
-## References
+| Mode | Trigger Condition | Behavior |
+|------|-------------------|----------|
+| **First Implementation** | tasks.md all `[ ]` | Start from MP1.1 |
+| **Resume from Breakpoint** | tasks.md has some `[x]` | Continue from first `[ ]` after last `[x]` |
+| **Gate Fix** | Test failures need fixing | Prioritize failed items |
 
-Required:
-- `~/.claude/skills/_shared/references/ai-behavior-guidelines.md`
-- `references/code-implementation-prompt.md`
+### Prerequisite Checks
 
-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`
+- [ ] `tasks.md` exists
+- [ ] `verification.md` exists
+- [ ] Test Owner not executed in current session
+- [ ] `tests/**` has test files