claude-dev-env 1.19.3 → 1.20.1

package/scripts/sync_to_cursor/rules.py

@@ -0,0 +1,321 @@
+"""Build Cursor .mdc bodies from Claude rules and docs."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from sync_to_cursor.config import MAX_RULE_BODY_LINES
+
+
+def _parse_h2_sections(markdown: str) -> dict[str, str]:
+    parts = re.split(r"^## ", markdown, flags=re.MULTILINE)
+    sections: dict[str, str] = {}
+    for part in parts[1:]:
+        title_line, _, body = part.partition("\n")
+        sections[title_line.strip()] = body.strip()
+    return sections
+
+
+def _filter_core_principles(body: str) -> str:
+    lines = []
+    for line in body.splitlines():
+        if "readability-review" in line or "readability standard" in line:
+            continue
+        lines.append(line)
+    return "\n".join(lines).strip()
+
+
+def _limit_lines(text: str, max_lines: int) -> str:
+    lines = text.splitlines()
+    if len(lines) <= max_lines:
+        return text
+    return (
+        "\n".join(lines[:max_lines])
+        + "\n\n_(Truncated for Cursor rule length; see the synced reference in `.cursor/docs/` "
+        "(`CODE_RULES.md` or `TEST_QUALITY.md` as applicable) and follow its canonical source "
+        "under `~/.claude/system-prompts/software-engineer.xml` when needed.)_"
+    )
+
+
+def _strip_code_standards_blockquote(markdown: str) -> str:
+    lines = markdown.splitlines()
+    out: list[str] = []
+    i = 0
+    while i < len(lines):
+        if lines[i].startswith(">") and "MANDATORY REFERENCE" in lines[i]:
+            while i < len(lines) and lines[i].startswith(">"):
+                i += 1
+            while i < len(lines) and lines[i].strip() == "":
+                i += 1
+            continue
+        out.append(lines[i])
+        i += 1
+    return "\n".join(out).strip()
+
+
+def merge_code_standards(sources: tuple[Path, ...]) -> str:
+    code_standards_markdown = _strip_code_standards_blockquote(
+        sources[0].read_text(encoding="utf-8")
+    )
+    code_standards_markdown = "\n".join(
+        line for line in code_standards_markdown.splitlines() if not line.strip().startswith("- TDD ")
+    )
+    code_rules_markdown = sources[1].read_text(encoding="utf-8")
+    sections_by_heading = _parse_h2_sections(code_rules_markdown)
+    if not sections_by_heading:
+        pointer_fallback_note = (
+            "_(Full code-quality rules: `~/.claude/system-prompts/software-engineer.xml`"
+            " under `<code_quality>`.)_"
+        )
+        chunks = [code_standards_markdown, "", pointer_fallback_note]
+        return _limit_lines("\n\n".join(chunks), MAX_RULE_BODY_LINES)
+    include_order = [
+        "COMMENT PRESERVATION (ABSOLUTE RULE)",
+        "CORE PRINCIPLES",
+        "⚡ HOOK-ENFORCED RULES",
+        "4. CONFIG LOCATIONS",
+        "5. NO ABBREVIATIONS",
+        "6. COMPLETE TYPE HINTS",
+        "9. SELF-CONTAINED COMPONENTS",
+    ]
+    chunks = [
+        code_standards_markdown,
+        "",
+        "## Reference (full text: `.cursor/docs/CODE_RULES.md`)",
+    ]
+    for title in include_order:
+        body = sections_by_heading.get(title, "")
+        if title == "CORE PRINCIPLES":
+            body = _filter_core_principles(body)
+        if body:
+            chunks.append(f"## {title}\n\n{body}")
+    merged = "\n\n".join(chunks)
+    return _limit_lines(merged, MAX_RULE_BODY_LINES)
+
+
+def merge_test_quality(sources: tuple[Path, ...]) -> str:
+    testing = sources[0].read_text(encoding="utf-8").strip()
+    test_quality_markdown = sources[1].read_text(encoding="utf-8")
+    sections_by_heading = _parse_h2_sections(test_quality_markdown)
+    include_order = [
+        "Delete Useless Tests",
+        "Test Dependencies MUST FAIL",
+        "Core Testing Principles",
+        "React Testing Patterns",
+        "Test File Organization",
+    ]
+    chunks = [testing, "", "## Reference (full text: `.cursor/docs/TEST_QUALITY.md`)"]
+    for title in include_order:
+        body = sections_by_heading.get(title, "")
+        if body:
+            chunks.append(f"## {title}\n\n{body}")
+    merged = "\n\n".join(chunks)
+    return _limit_lines(merged, MAX_RULE_BODY_LINES)
+
+
+def strip_anthropic_refs(text: str) -> str:
+    out_lines: list[str] = []
+    for line in text.splitlines():
+        s = line.strip()
+        if s.startswith("Source:") and (
+            "anthropic" in s.lower()
+            or "claude.com" in s.lower()
+            or "docs.anthropic" in s.lower()
+        ):
+            continue
+        if "docs.anthropic.com" in line:
+            continue
+        out_lines.append(line)
+    text = "\n".join(out_lines)
+    text = re.sub(
+        r"<do_not_act_before_instructions>\s*",
+        "",
+        text,
+        flags=re.DOTALL,
+    )
+    text = re.sub(r"\s*</do_not_act_before_instructions>", "", text)
+    return text.strip()
+
+
+def verbatim(text: str) -> str:
+    return text.strip()
+
+
+def near_verbatim(text: str) -> str:
+    return strip_anthropic_refs(text)
+
+
+def strip_leading_yaml_frontmatter(text: str) -> str:
+    """Remove leading `---` ... `---` block (e.g. Claude `paths:`) so Cursor `.mdc` uses its own frontmatter."""
+    lines = text.splitlines()
+    if not lines or lines[0].strip() != "---":
+        return text
+    for i in range(1, len(lines)):
+        if lines[i].strip() == "---":
+            return "\n".join(lines[i + 1 :]).lstrip("\n")
+    return text
+
+
+TransformName = Literal["verbatim", "near_verbatim", "merge_code_standards", "merge_test_quality"]
+
+
+def apply_transform(
+    name: TransformName,
+    sources: tuple[Path, ...],
+    *,
+    strip_leading_frontmatter: bool = False,
+) -> str:
+    if name == "merge_code_standards":
+        return merge_code_standards(sources)
+    if name == "merge_test_quality":
+        return merge_test_quality(sources)
+    raw = "\n\n".join(p.read_text(encoding="utf-8") for p in sources)
+    if strip_leading_frontmatter:
+        raw = strip_leading_yaml_frontmatter(raw)
+    if name == "verbatim":
+        return verbatim(raw)
+    if name == "near_verbatim":
+        return near_verbatim(raw)
+    raise AssertionError(name)
+
+
+@dataclass(frozen=True)
+class RuleMapping:
+    key: str
+    sources: tuple[Path, ...]
+    output_name: str
+    always_apply: bool
+    globs: str | None
+    description: str
+    transform: TransformName
+    strip_leading_frontmatter: bool = False
+
+
+def _frontmatter(description: str, always_apply: bool, globs: str | None) -> str:
+    escaped_description = description.replace('"', '\\"')
+    lines = ["---", f'description: "{escaped_description}"']
+    if globs:
+        escaped_globs = globs.replace('"', '\\"')
+        lines.append(f'globs: "{escaped_globs}"')
+    lines.append(f"alwaysApply: {'true' if always_apply else 'false'}")
+    lines.append("---")
+    return "\n".join(lines) + "\n"
+
+
+def _full_mdc(mapping: RuleMapping, body: str) -> str:
+    generated_header = (
+        "<!-- Generated by sync-to-cursor.py — do not edit directly -->\n"
+        "<!-- Re-run: python ~/.claude/scripts/sync-to-cursor.py -->\n"
+        "<!-- Output: .cursor/rules/*.mdc, .cursor/docs/*.md"
+        " (see LLM_SETTINGS_ROOT in script docstring) -->\n"
+    )
+    return _frontmatter(mapping.description, mapping.always_apply, mapping.globs) + "\n" + generated_header + "\n" + body + "\n"
+
+
+def _read_paths_glob(rule_file: Path) -> str | None:
+    """Read `paths:` list from a Claude rule's YAML frontmatter; return as comma-separated Cursor glob string."""
+    if not rule_file.is_file():
+        return None
+    lines = rule_file.read_text(encoding="utf-8").splitlines()
+    if not lines or lines[0].strip() != "---":
+        return None
+    is_in_paths = False
+    all_paths: list[str] = []
+    for line in lines[1:]:
+        if line.strip() == "---":
+            break
+        if line.startswith("paths:"):
+            is_in_paths = True
+            continue
+        if is_in_paths:
+            if line.startswith(" ") or line.startswith("\t"):
+                path_value = line.strip().lstrip("-").strip().strip('"').strip("'")
+                if path_value:
+                    all_paths.append(path_value)
+            else:
+                is_in_paths = False
+    return ",".join(all_paths) if all_paths else None
+
+
+def build_mappings(claude: Path) -> tuple[RuleMapping, ...]:
+    rules_directory = claude / "rules"
+    docs_directory = claude / "docs"
+    test_globs = "**/*.test.*,**/*.spec.*,**/test_*,**/*_test.*"
+    return (
+        RuleMapping(
+            "code-standards",
+            (rules_directory / "code-standards.md", docs_directory / "CODE_RULES.md"),
+            "code-standards.mdc",
+            True,
+            None,
+            "Core code standards: naming, types, config, hook-enforced rules",
+            "merge_code_standards",
+        ),
+        RuleMapping(
+            "tasklings-preferences",
+            (rules_directory / "tasklings-preferences.md",),
+            "tasklings-preferences.mdc",
+            False,
+            _read_paths_glob(rules_directory / "tasklings-preferences.md"),
+            "Tasklings: Prefer / Do / Always engineering preferences (scoped path)",
+            "verbatim",
+            True,
+        ),
+        RuleMapping(
+            "right-sized-engineering",
+            (rules_directory / "right-sized-engineering.md",),
+            "right-sized-engineering.mdc",
+            True,
+            None,
+            "Right-sized engineering and complexity budget",
+            "verbatim",
+        ),
+        RuleMapping(
+            "bdd",
+            (rules_directory / "bdd.md",),
+            "bdd.mdc",
+            True,
+            None,
+            "BDD: discovery-driven protocol (outside-in; Illustrate→Formulate→Automate)",
+            "verbatim",
+        ),
+        RuleMapping(
+            "test-quality",
+            (rules_directory / "testing.md", docs_directory / "TEST_QUALITY.md"),
+            "test-quality.mdc",
+            False,
+            test_globs,
+            "Testing quality for test files",
+            "merge_test_quality",
+        ),
+        RuleMapping(
+            "research-mode",
+            (rules_directory / "research-mode.md",),
+            "research-mode.mdc",
+            True,
+            None,
+            "Research mode: citations and I don't know",
+            "near_verbatim",
+        ),
+        RuleMapping(
+            "conservative-action",
+            (rules_directory / "conservative-action.md",),
+            "conservative-action.mdc",
+            True,
+            None,
+            "Prefer research over action when intent is unclear",
+            "near_verbatim",
+        ),
+        RuleMapping(
+            "explore-thoroughly",
+            (rules_directory / "explore-thoroughly.md",),
+            "explore-thoroughly.mdc",
+            True,
+            None,
+            "Explore codebase before committing to an approach",
+            "near_verbatim",
+        ),
+    )

package/scripts/tests/test_sync_to_cursor.py

@@ -0,0 +1,255 @@
+"""Tests for sync-to-cursor.py: canonical docs copy, manifest, and truncation footer."""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+_SCRIPTS_DIR = Path(__file__).resolve().parent.parent
+if str(_SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIR))
+
+import sync_to_cursor as mod
+from sync_to_cursor.rules import _read_paths_glob
+
+_SYNC_SCRIPT = _SCRIPTS_DIR / "sync-to-cursor.py"
+
+
+def _minimal_rule_files(claude_rules: Path) -> None:
+    claude_rules.mkdir(parents=True, exist_ok=True)
+    (claude_rules / "code-standards.md").write_text(
+        "# Code standards stub\n", encoding="utf-8"
+    )
+    (claude_rules / "tasklings-preferences.md").write_text(
+        "---\npaths:\n  - \"Y:/x/**\"\n---\n\n# Tasklings\n",
+        encoding="utf-8",
+    )
+    (claude_rules / "right-sized-engineering.md").write_text("# RSE\n", encoding="utf-8")
+    (claude_rules / "bdd.md").write_text("# BDD\n", encoding="utf-8")
+    (claude_rules / "testing.md").write_text("# Testing\n", encoding="utf-8")
+    (claude_rules / "research-mode.md").write_text("# RM\n", encoding="utf-8")
+    (claude_rules / "conservative-action.md").write_text("# CA\n", encoding="utf-8")
+    (claude_rules / "explore-thoroughly.md").write_text("# ET\n", encoding="utf-8")
+
+
+def _minimal_code_rules_and_test_quality(claude_docs: Path) -> tuple[bytes, bytes]:
+    claude_docs.mkdir(parents=True, exist_ok=True)
+    cr = b"## CORE PRINCIPLES\n\nalpha\n"
+    tq = b"## Core Testing Principles\n\nbeta\n"
+    (claude_docs / "CODE_RULES.md").write_bytes(cr)
+    (claude_docs / "TEST_QUALITY.md").write_bytes(tq)
+    return cr, tq
+
+
+def test_limit_lines_footer_mentions_cursor_docs() -> None:
+    long_body = "\n".join(f"line {index}" for index in range(mod.MAX_RULE_BODY_LINES + 5))
+    out = mod._limit_lines(long_body, mod.MAX_RULE_BODY_LINES)
+    assert ".cursor/docs" in out
+    assert "synced reference" in out
+    assert "~/.claude/system-prompts/software-engineer.xml" in out
+
+
+def test_sync_canonical_docs_copies_byte_identical(tmp_path: Path) -> None:
+    claude = tmp_path / ".claude"
+    cursor = tmp_path / ".cursor"
+    docs = claude / "docs"
+    cr, tq = _minimal_code_rules_and_test_quality(docs)
+    mod._sync_canonical_docs(claude, cursor, dry_run=False, quiet=True)
+    assert (cursor / "docs" / "CODE_RULES.md").read_bytes() == cr
+    assert (cursor / "docs" / "TEST_QUALITY.md").read_bytes() == tq
+
+
+def test_sync_canonical_docs_skips_missing_with_no_dst(tmp_path: Path) -> None:
+    claude = tmp_path / ".claude"
+    cursor = tmp_path / ".cursor"
+    (claude / "docs").mkdir(parents=True)
+    (claude / "docs" / "CODE_RULES.md").write_text("x", encoding="utf-8")
+    mod._sync_canonical_docs(claude, cursor, dry_run=False, quiet=True)
+    assert (cursor / "docs" / "CODE_RULES.md").read_text(encoding="utf-8") == "x"
+    assert not (cursor / "docs" / "TEST_QUALITY.md").is_file()
+
+
+def test_check_fails_when_doc_source_changes_without_resync(tmp_path: Path) -> None:
+    claude = tmp_path / ".claude"
+    cursor = tmp_path / ".cursor"
+    _minimal_rule_files(claude / "rules")
+    _minimal_code_rules_and_test_quality(claude / "docs")
+    env = {**os.environ, "LLM_SETTINGS_ROOT": str(tmp_path)}
+    subprocess.run(
+        [sys.executable, str(_SYNC_SCRIPT), "--force"],
+        env=env,
+        check=True,
+        cwd=str(_SCRIPTS_DIR),
+    )
+    (claude / "docs" / "CODE_RULES.md").write_bytes(b"changed\n")
+    subprocess_result = subprocess.run(
+        [sys.executable, str(_SYNC_SCRIPT), "--check"],
+        env=env,
+        cwd=str(_SCRIPTS_DIR),
+    )
+    assert subprocess_result.returncode != 0
+
+
+def test_check_passes_after_resync(tmp_path: Path) -> None:
+    claude = tmp_path / ".claude"
+    cursor = tmp_path / ".cursor"
+    _minimal_rule_files(claude / "rules")
+    _minimal_code_rules_and_test_quality(claude / "docs")
+    env = {**os.environ, "LLM_SETTINGS_ROOT": str(tmp_path)}
+    subprocess.run(
+        [sys.executable, str(_SYNC_SCRIPT), "--force"],
+        env=env,
+        check=True,
+        cwd=str(_SCRIPTS_DIR),
+    )
+    subprocess_result = subprocess.run(
+        [sys.executable, str(_SYNC_SCRIPT), "--check"],
+        env=env,
+        cwd=str(_SCRIPTS_DIR),
+    )
+    assert subprocess_result.returncode == 0
+
+
+def test_manifest_includes_docs_entries(tmp_path: Path) -> None:
+    claude = tmp_path / ".claude"
+    cursor = tmp_path / ".cursor"
+    _minimal_rule_files(claude / "rules")
+    _minimal_code_rules_and_test_quality(claude / "docs")
+    env = {**os.environ, "LLM_SETTINGS_ROOT": str(tmp_path)}
+    subprocess.run(
+        [sys.executable, str(_SYNC_SCRIPT), "--force"],
+        env=env,
+        check=True,
+        cwd=str(_SCRIPTS_DIR),
+    )
+    manifest = json.loads((cursor / ".sync-manifest.json").read_text(encoding="utf-8"))
+    assert "docs_entries" in manifest
+    de = manifest["docs_entries"]
+    assert "docs/CODE_RULES.md" in de
+    assert "docs/TEST_QUALITY.md" in de
+    assert "sources_hash" in de["docs/CODE_RULES.md"]
+    assert "output_hash" in de["docs/CODE_RULES.md"]
+
+
+def test_merge_code_standards_with_pointer_style_code_rules(tmp_path: Path) -> None:
+    rules_directory = tmp_path / "rules"
+    docs_directory = tmp_path / "docs"
+    rules_directory.mkdir(parents=True, exist_ok=True)
+    docs_directory.mkdir(parents=True, exist_ok=True)
+    (rules_directory / "code-standards.md").write_text(
+        "# Code standards stub\n\n- Use full words\n", encoding="utf-8"
+    )
+    (docs_directory / "CODE_RULES.md").write_text(
+        "# CODE_RULES pointer: canonical code-quality policy lives in"
+        " `~/.claude/system-prompts/software-engineer.xml` under `<code_quality>`.\n",
+        encoding="utf-8",
+    )
+    merged = mod.merge_code_standards(
+        (rules_directory / "code-standards.md", docs_directory / "CODE_RULES.md")
+    )
+    assert merged.strip(), "output must not be empty for pointer-style CODE_RULES.md"
+    assert "software-engineer.xml" in merged
+    assert "code_quality" in merged
+
+
+def test_sync_canonical_docs_deletes_stale_copy_when_source_removed(tmp_path: Path) -> None:
+    claude = tmp_path / ".claude"
+    cursor = tmp_path / ".cursor"
+    _minimal_code_rules_and_test_quality(claude / "docs")
+    mod._sync_canonical_docs(claude, cursor, dry_run=False, quiet=True)
+    assert (cursor / "docs" / "CODE_RULES.md").is_file()
+    (claude / "docs" / "CODE_RULES.md").unlink()
+    mod._sync_canonical_docs(claude, cursor, dry_run=False, quiet=True)
+    assert not (cursor / "docs" / "CODE_RULES.md").is_file()
+
+
+def test_dry_run_does_not_create_output_directory(tmp_path: Path) -> None:
+    claude = tmp_path / ".claude"
+    cursor = tmp_path / ".cursor"
+    _minimal_rule_files(claude / "rules")
+    _minimal_code_rules_and_test_quality(claude / "docs")
+    env = {**os.environ, "LLM_SETTINGS_ROOT": str(tmp_path)}
+    subprocess.run(
+        [sys.executable, str(_SYNC_SCRIPT), "--dry-run", "--quiet"],
+        env=env,
+        check=True,
+        cwd=str(_SCRIPTS_DIR),
+    )
+    assert not (cursor / "rules").exists(), "--dry-run must not create the output directory"
+
+
+def test_check_skips_optional_mapping_when_source_missing(tmp_path: Path) -> None:
+    claude = tmp_path / ".claude"
+    cursor = tmp_path / ".cursor"
+    _minimal_rule_files(claude / "rules")
+    _minimal_code_rules_and_test_quality(claude / "docs")
+    env = {**os.environ, "LLM_SETTINGS_ROOT": str(tmp_path)}
+    subprocess.run(
+        [sys.executable, str(_SYNC_SCRIPT), "--force"],
+        env=env,
+        check=True,
+        cwd=str(_SCRIPTS_DIR),
+    )
+    (claude / "rules" / "tasklings-preferences.md").unlink()
+    subprocess_result = subprocess.run(
+        [sys.executable, str(_SYNC_SCRIPT), "--check"],
+        env=env,
+        cwd=str(_SCRIPTS_DIR),
+    )
+    assert subprocess_result.returncode == 0, "--check must pass when only optional sources are missing"
+
+
+def test_tasklings_glob_derived_from_frontmatter(tmp_path: Path) -> None:
+    rules_directory = tmp_path / "rules"
+    rules_directory.mkdir(parents=True)
+    (rules_directory / "tasklings-preferences.md").write_text(
+        '---\npaths:\n  - "Y:/MyProject/**"\n  - "Z:/Other/**"\n---\n\n# Tasklings\n',
+        encoding="utf-8",
+    )
+    glob_value = _read_paths_glob(rules_directory / "tasklings-preferences.md")
+    assert glob_value == "Y:/MyProject/**,Z:/Other/**"
+
+
+def test_merge_reference_headers_point_at_cursor_docs(tmp_path: Path) -> None:
+    rules_directory = tmp_path / "rules"
+    docs_directory = tmp_path / "docs"
+    rules_directory.mkdir(parents=True, exist_ok=True)
+    docs_directory.mkdir(parents=True, exist_ok=True)
+    (rules_directory / "code-standards.md").write_text("# CS\n", encoding="utf-8")
+    cr_body = "\n\n".join(
+        f"## {t}\n\nbody"
+        for t in [
+            "COMMENT PRESERVATION (ABSOLUTE RULE)",
+            "CORE PRINCIPLES",
+            "⚡ HOOK-ENFORCED RULES",
+            "4. CONFIG LOCATIONS",
+            "5. NO ABBREVIATIONS",
+            "6. COMPLETE TYPE HINTS",
+            "9. SELF-CONTAINED COMPONENTS",
+        ]
+    )
+    (docs_directory / "CODE_RULES.md").write_text(cr_body, encoding="utf-8")
+    merged = mod.merge_code_standards(
+        (rules_directory / "code-standards.md", docs_directory / "CODE_RULES.md")
+    )
+    assert ".cursor/docs/CODE_RULES.md" in merged
+
+    (rules_directory / "testing.md").write_text("# T\n", encoding="utf-8")
+    tq_body = "\n\n".join(
+        f"## {t}\n\nbody"
+        for t in [
+            "Delete Useless Tests",
+            "Test Dependencies MUST FAIL",
+            "Core Testing Principles",
+            "React Testing Patterns",
+            "Test File Organization",
+        ]
+    )
+    (docs_directory / "TEST_QUALITY.md").write_text(tq_body, encoding="utf-8")
+    merged_tq = mod.merge_test_quality(
+        (rules_directory / "testing.md", docs_directory / "TEST_QUALITY.md")
+    )
+    assert ".cursor/docs/TEST_QUALITY.md" in merged_tq

package/skills/bdd-protocol/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: bdd-protocol
+description: >-
+  On-demand BDD depth aligned with jl-cmd/claude-code-config#82: Example Mapping (Smart &
+  Molak §6.4), scenario quality and anti-patterns (§7.6), solo minimal BDD, outside-in test
+  layout. Use when expanding `<behavior_protocol>` in the system prompt, writing executable
+  specifications, or when the user asks for discovery, "the one where" examples, or BDD
+  scenario quality. Triggers: bdd-protocol, Example Mapping, BDD anti-patterns, §7.6.
+---
+@~/.claude/skills/bdd-protocol/references/example-mapping.md
+@~/.claude/skills/bdd-protocol/references/anti-patterns.md
+
+# BDD protocol (on-demand)
+
+The always-on sequence lives in `~/.claude/system-prompts/software-engineer.xml` under `<behavior_protocol>` (Deliberate Discovery → Illustrate → Formulate → Automate). This skill adds **depth** you load when you need algorithms, catalogs, or layout guidance.
+
+## When to use this skill
+
+- The user or task needs **Example Mapping** steps, parking-lot questions, or "the one where …" phrasing.
+- You are writing or reviewing **scenarios** and need the **§7.6** quality bar and anti-patterns.
+- You are organizing **tests by behavior** (describe / when / should) or using **soap-opera personas** for solo work.
+
+## Authority
+
+- John Ferguson Smart & Jan Molak, *BDD in Action* 2e (Manning, 2023) — §2.3.7 outside-in, §5.4 Deliberate Discovery, §6.4 Example Mapping, §7.6 scenario quality, §16.5.5 test layout.
+- Dan North, "Introducing BDD" (2006).
+- John Ferguson Smart, Minimal BDD (learnbdd.com; Wayback-cited in tracking issue).
+
+## What stays in the system prompt
+
+Do not duplicate the four-phase sequence here; keep a single source of truth in `<behavior_protocol>`.

package/skills/bdd-protocol/references/anti-patterns.md

@@ -0,0 +1,26 @@
+# Scenario quality and anti-patterns (§7.6 and related)
+
+Use this as a **checklist** when writing or reviewing scenarios and developer-facing specifications. Phrasing follows *BDD in Action* 2e and the catalog summarized in [claude-code-config#82](https://github.com/jl-cmd/claude-code-config/issues/82).
+
+## Positive targets (what "good" looks like)
+
+- **Declarative focus (§7.6.3):** Scenarios describe **business behavior** and user goals, not low-level UI click scripts.
+- **Single-rule focus (§7.6.4):** One **business rule** per scenario; split when a scenario grows hard to read.
+- **Meaningful actors (§7.6.5):** Personas can be **lightweight** (e.g. soap-opera introductions) when full UX research is unavailable — name + role, grow detail as scenarios demand.
+- **Essential detail (§7.6.6):** Include data and columns that **change outcomes**; omit neutral or redundant columns.
+- **State clarity (§7.6.6):** Make **initial** and **final** state explicit when data illustrates behavior.
+- **Outcome description (§7.6.7):** Outcomes are **observable and measurable** — not hidden behind vague "verify" steps.
+- **Independence (§7.6.8):** Each scenario sets up **its own** data and state so it can run alone.
+
+## Anti-patterns to refuse or rewrite
+
+- **Imperative scenarios** that read like automation scripts (especially pure UI step lists).
+- **Multi-concern** scenarios that mix unrelated rules.
+- **Incidental detail** that does not serve the rule under test.
+- **Test scripts in disguise** — heavy use of **verify** / **check** without stating the business outcome.
+- **Dependent scenarios** that only pass in order.
+- **Gherkin without conversation** (BAs or testers writing scenarios in isolation) — structured specs are an **output** of discovery, not a substitute for it (Minimal BDD).
+
+## Executable specs at the code level
+
+Prefer **"should …"** phrasing in names (Dan North, 2006). Nest by **behavior context** (e.g. when / given groupings) rather than mirroring production file layout when that obscures intent (§16.5.5 attitude: tests as documentation).

package/skills/bdd-protocol/references/example-mapping.md

@@ -0,0 +1,23 @@
+# Example Mapping (Smart & Molak §6.4)
+
+Lightweight, breadth-first discovery before code. Sessions are typically **25–30 minutes**.
+
+## Core moves
+
+- State **rules**, then ask for an **example of each** rule. Examples often use **"The one where …"** phrasing (Daniel Terhorst-North; sometimes called "Friends episode notation").
+- For each example, probe with **"What if …?"**, **"Is this always the case?"**, **"Are there examples where this rule behaves differently?"** Probes can surface **new rules**; add examples for those rules.
+- **Pink cards**: questions that cannot be answered yet — **park** them; do not pretend they are specifications.
+
+## Chat algorithm (solo-friendly)
+
+1. **Restate the rule or feature** until it is clearly defined.
+2. Generate **3–5** "the one where …" examples from simple to complex.
+3. For each example, run the **three probes** above.
+4. If probes reveal a **new rule** or materially different behavior, add **2–3** examples for that rule and continue probing.
+5. Repeat until examples for each rule are probed.
+6. Compile **rules + examples + parked questions**; confirm with the user before automating tests.
+7. **Time-box** discovery; proceed to failing tests only after the map is agreed.
+
+## Parking lot discipline
+
+Unanswered questions stay **out of automated tests** until resolved or explicitly accepted as follow-up work.

package/skills/npm-creator/SKILL.md

@@ -74,8 +74,8 @@ For each detected directory from Step 1:
 - Copy files from package to CLAUDE_HOME, preserving directory structure
 - For skills/, copy recursively (each skill is a subdirectory)
 - For each file, log with status icon:
-  - New file: `  ✓ rules/tdd.md (new)`
-  - Existing file: `  ↻ rules/tdd.md (updated)`
+  - New file: `  ✓ rules/bdd.md (new)`
+  - Existing file: `  ↻ rules/bdd.md (updated)`
 
 If CLAUDE.md generation is enabled:
 - Concatenate all rules/*.md under `# Project Rules (from <package-name> plugin)`
@@ -112,7 +112,7 @@ Installed <package-name>:
 
 **Uninstall mode (`--uninstall` flag):**
 - Remove only files matching the package's file list (never delete user-created files)
-- Log each removal: `  ✗ rules/tdd.md (removed)`
+- Log each removal: `  ✗ rules/bdd.md (removed)`
 - Remove hook entries from settings.json by matching command paths
 - Remove generated CLAUDE.md if it exists
 - Print removal summary