claude-dev-env 1.19.3 → 1.21.0

package/CLAUDE.md

@@ -0,0 +1,43 @@
+# Claude Development Assistant
+
+## Code Rules (NON-NEGOTIABLE)
+@~/.claude/docs/CODE_RULES.md
+
+## Core Philosophy
+
+**TDD IS NON-NEGOTIABLE.** Build it right, build it simple. Maintainable > Clever.
+
+## Working with Claude
+
+### Expectations
+
+1. **ALWAYS FOLLOW TDD** - No production code without failing test
+2. **MANDATORY SELF-CHECK before proposing** - See protocol below
+3. Assess refactoring after every green
+
+### Mandatory Self-Check Protocol
+
+**BEFORE proposing plans/implementation:**
+
+☐ Project rules review (e.g. Tasklings `tasklings-preferences` when in that repo path)
+☐ "Is this KISS?" (simplest? unnecessary complexity?)
+☐ "Over-engineering?" (multiple files? premature abstractions?)
+☐ Test infrastructure? (ONE file, functions, YAGNI)
+☐ Tests add value? (no existence checks, no constant tests)
+
+## Pre-PR Submission Checklist
+
+**Run `/check-pr` OR verify:**
+- ☐ KISS / preferences (multiple requirements.txt? over-engineered?)
+- ☐ KISS (simplest? one file? functions not classes?)
+- ☐ Files (proper modules, correct dirs, no empty __init__.py)
+- ☐ Quality (no dupes, types complete, no Any/any)
+- ☐ Tests (no existence checks, no constant value tests)
+- ☐ Self-checked before proposing?
+
+## Compaction
+When compacting, always preserve:
+- Active task and current goal
+- Full list of modified files
+- Any failing test names or error messages
+- Current git branch and PR state

package/bin/install.mjs

@@ -13,7 +13,7 @@ const MANIFEST_FILE = join(CLAUDE_HOME, '.claude-dev-env-manifest.json');
 const PACKAGE_NAME = 'claude-dev-env';
 const packageRequire = createRequire(import.meta.url);
 
-const CONTENT_DIRECTORIES = ['rules', 'docs', 'commands', 'agents'];
+const CONTENT_DIRECTORIES = ['rules', 'docs', 'commands', 'agents', 'system-prompts', 'scripts'];
 
 function resolveDependencyPackageRoot(dependencyPackageName) {
     const dependencyPackageJsonPath = packageRequire.resolve(
@@ -152,6 +152,23 @@ function copyTree(sourceBase, destBase) {
     return stats;
 }
 
+/**
+ * If destPath exists and differs from incomingPath, copy the existing file to
+ * ~/.claude/backups/CLAUDE.md.<timestamp>.bak before the installer overwrites it.
+ */
+function backupClaudeHubBeforeOverwrite(destPath, incomingPath) {
+    if (!existsSync(destPath)) return null;
+    const existingBytes = readFileSync(destPath);
+    const incomingBytes = readFileSync(incomingPath);
+    if (existingBytes.equals(incomingBytes)) return null;
+    const backupsDir = join(CLAUDE_HOME, 'backups');
+    mkdirSync(backupsDir, { recursive: true });
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const backupPath = join(backupsDir, `CLAUDE.md.${stamp}.bak`);
+    copyFileSync(destPath, backupPath);
+    return backupPath;
+}
+
 function mergeHooks(hooksSourceRoot, pythonCommand) {
     const hooksJsonPath = join(hooksSourceRoot, 'hooks', 'hooks.json');
     if (!existsSync(hooksJsonPath)) return 0;
@@ -338,6 +355,19 @@ function install(selectedGroups) {
         summary.hookGroups = totalHookGroups;
         console.log(`  Hook groups: ${totalHookGroups} merged into settings.json`);
     }
+    const claudeHubSource = join(PACKAGE_ROOT, 'CLAUDE.md');
+    if (existsSync(claudeHubSource)) {
+        const claudeHubDest = join(CLAUDE_HOME, 'CLAUDE.md');
+        const backupPath = backupClaudeHubBeforeOverwrite(claudeHubDest, claudeHubSource);
+        if (backupPath) {
+            console.log(
+                `  \u21bb ${relative(CLAUDE_HOME, backupPath)} (previous CLAUDE.md hub preserved)`
+            );
+        }
+        copyFileSync(claudeHubSource, claudeHubDest);
+        allInstalledFiles.push(claudeHubDest);
+        console.log(`  \u2713 ${relative(CLAUDE_HOME, claudeHubDest)} (hub)`);
+    }
     writeManifest(allInstalledFiles);
     console.log(`\nInstalled ${PACKAGE_NAME}:`);
     for (const directory of CONTENT_DIRECTORIES) {
@@ -423,6 +453,9 @@ Examples:
   npx ${PACKAGE_NAME} --only prompt-generator,research
 
 Install location: ~/.claude/
+
+If ~/.claude/CLAUDE.md already exists and differs from the package copy, the installer
+writes the previous contents to ~/.claude/backups/CLAUDE.md.<timestamp>.bak first.
 `);
 }
 

package/docs/BDD_DISCOVERY_PROTOCOL.md

@@ -0,0 +1,53 @@
+# BDD Discovery Protocol
+
+This protocol guides Claude through **Example Mapping** to discover test ideas from user requests before writing code. Work **breadth-first**: map rules, examples, and unknowns first; park unresolved questions instead of guessing. Based on Smart & Molak *BDD in Action* §6.4 and Dan North, "Introducing BDD" (2006).
+
+> §6.4.2: "The team discuss the rules and asks for an example of each. Examples are often described using a short phrase that starts with the words 'The one where ...' This notation, originally described by Daniel Terhorst-North, is known as the 'Friends episode notation', from the 90s TV series of the same name."
+
+> §6.4.4: "Questions that can't be answered immediately are noted as pink cards."
+
+> §6.4.5: "Example Mapping sessions should be quite short; 25–30 minutes is usually enough to get through a story."
+
+## Core algorithm
+
+1. **State the rule or feature** — Restate until the rule is clearly defined. *Exit:* shared understanding of what we are exploring.
+
+2. **Generate examples** — Produce 3–5 phrases using **"The one where …"** notation, simple to complex. *Exit:* examples cover the rule’s scope without duplicating the same case.
+
+3. **Probe the first unchecked example** — Ask: *What if …?* *Is this always the case?* *Are there examples where this rule behaves differently?* *Exit:* all three probes asked for this example.
+
+4. **Evaluate answers** — When a new rule emerges, return to Step 3 for that rule. New edge cases may become **new rules** (add 2–3 examples each). Questions you cannot answer become **parked items**. *Exit:* probes for this example are processed.
+
+5. **Next example** — Repeat steps 3–4. *Exit:* all examples probed.
+
+6. **Compile and confirm** — In steady state, present a full compile of rules, examples, and parking lot. Ask: "Does this Example Map cover the behavior you need? Any rules or examples to add, remove, or refine?" *Exit:* user confirms; exit when user confirms.
+
+7. **Time-box and exit** — Keep discovery within ~25–30 minutes when possible; also **exit** when tests are under way or the session ends.
+
+> "What to call your test is easy: it's a sentence describing the next behaviour in which you are interested." — Dan North (2006)
+
+## Worked Example: Theme Asset Release Date Validation
+
+- **Rule:** A theme asset must not go live before its configured release date.
+- **Examples (the one where …):**
+  - … the release date is tomorrow and today’s import runs — should block or warn
+  - … the release date was last week — should allow publish
+  - … the release date field is empty — should use policy default
+  - … the release date is updated after a draft was already scheduled — should re-validate against policy
+- **Probe:** *What if the server timezone is UTC but the editor is local?* → Surfaces a **new rule** about timezone for "release day."
+- **New rule examples:** same calendar date in UTC vs local; DST boundary.
+- **Parked:** certification API does not return a timezone — follow up with vendor.
+
+## Using This Protocol
+
+- State the business rule clearly
+- Generate concrete examples (the one where ...)
+- Probe each example with three question forms
+- Capture open questions as a parked list for later resolution
+- Compile and confirm the Example Map with the user
+- Proceed to test writing only after user approval
+
+## References
+
+- Smart & Molak, *BDD in Action* 2e, Chapter 6, §6.4 (Example Mapping)
+- Dan North, "Introducing BDD" (2006), https://dannorth.net/blog/introducing-bdd/

package/docs/BDD_SCENARIO_QUALITY.md

@@ -0,0 +1,89 @@
+# BDD Scenario Quality Guide
+
+This guide defines the seven patterns that make scenarios clear, focused, and testable, enabling teams to align on business behavior, merge ideas from shared examples, and verify outcomes with automation and review.
+
+Source: Smart & Molak, *BDD in Action* 2e, Chapter 7.6 — scenario quality patterns.
+
+## Declarative Focus
+
+Scenarios work best when they name what users want to achieve in the language of the business. Lead with goals and recognizable domain tasks so readers grasp intent at a glance. Reserve step-level or UI detail for places where it truly clarifies behavior.
+
+> "Good scenarios model business behavior, not system interactions." — Smart & Molak §7.6.3
+
+Good scenarios name user goals and tasks in domain language before any implementation detail.
+
+## Single-Rule Focus
+
+Each scenario tests one business rule. When a rule is complex or a scenario grows hard to read, split it into smaller scenarios that each test one aspect of the rule. That keeps failures pointing to a single behavior.
+
+> "Good scenarios focus on testing a single business rule. If a business rule is complex, or if a scenario gets too big and hard to read, a good trick is to break the scenario into smaller, more focused ones that test a specific aspect of the rule." — Smart & Molak §7.6.4
+
+Good scenarios isolate one rule so failures point to a single behavior.
+
+### Example: hotel search (illustrates single-rule focus and declarative data)
+
+This scenario shows one rule: search returns hotels within a distance threshold.
+
+```
+Scenario: Search for available hotels by distance
+Given the following hotels:
+| Hotel Name | Location | Distance from center |
+| Ritz       | Paris    | 3.2                  |
+| Savoy      | Paris    | 6.9                  |
+| Hilton     | Paris    | 12.5                 |
+When I search for a hotel within 10 km of Paris
+Then I should be presented with the following hotels:
+| Hotel Name | Location | Distance from center |
+| Ritz       | Paris    | 3.2                  |
+| Savoy      | Paris    | 6.9                  |
+```
+
+## Meaningful Actors
+
+Personas ground scenarios in realistic goals and context. Use light soap-opera personas when you need depth before full UX research: introduce names and roles as needed and deepen them across scenarios.
+
+> Smart & Molak §7.6.5 describe personas as rich, realistic descriptions: each persona captures goals, abilities, and background information that ground the test scenario in a real user context.
+
+Good scenarios name who acts and what they need in plain language.
+
+## Essential Detail
+
+Include columns and fields that affect the outcome; verify each column contributes, and simplify tables where values repeat or stay neutral to the result. Every visible value should earn its place in the example.
+
+> Smart & Molak §7.6.6 — essential detail is information directly relevant to the business rule.
+
+Good scenarios tie every field to a value that changes the outcome.
+
+## State Clarity
+
+When examples use data to illustrate behavior, spell out the starting situation and the expected end state in the same breath. Set up or reference test data so the system begins in the expected initial state before the action. Readers should always see both the before and after picture when data carries the story.
+
+> "Well-written scenarios describe both behavior and data. When a scenario uses data to illustrate behavior, it should describe the initial state and the final state and manage or set up the test data to ensure that the system is in the expected initial state." — Smart & Molak §7.6.6
+
+Good scenarios state initial and final state when data illustrates behavior.
+
+## Outcome Description
+
+Well-written scenarios state target outcomes in clear, measurable terms any reader can verify—business results observers can confirm directly in the Then steps.
+
+> Smart & Molak §7.6.7 — scenarios state outcomes observers can confirm.
+
+Good scenarios describe observable outcomes in domain terms.
+
+## Independence
+
+Each scenario sets up its own data and system state so it can run alone; give every scenario a self-contained setup so the suite passes in any run order. Every scenario carries its own setup and makes preconditions explicit.
+
+> Smart & Molak §7.6.8 — independent scenarios work in isolation.
+
+Good scenarios carry their own setup and expose every precondition needed to run in any order.
+
+## Quick Reference
+
+- ✓ Scenarios describe user goals and business tasks in domain terms
+- ✓ Each scenario tests one business rule
+- ✓ Actors have recognizable goals and context
+- ✓ Tables and fields carry the information that affects the outcome
+- ✓ Initial and final state are clear when data matters
+- ✓ Outcomes are unambiguous and measurable
+- ✓ Scenarios run independently with their own data

package/docs/BDD_TEST_LAYOUT.md

@@ -0,0 +1,71 @@
+# BDD Test Layout and Personas
+
+Tests are **technical documentation**: they should read clearly when you return to the codebase after time away. Organize by **behavior and functional slice**, not necessarily by mirroring production file paths, when that aids navigation.
+
+For future readers, tests read as documentation: names, grouping, and **should** sentences should make behavior discoverable without opening production code first.
+
+> "Many organizations apply a looser association between test classes and production classes. … Test packages or directories organized in terms of functional slices are often easier to navigate." — Smart & Molak §16.5.5
+
+> "Writing unit tests that make good technical documentation relies more on an attitude than on using a particular tool." — Smart & Molak §16.5.5
+
+## Describe / when / should
+
+- Outermost **describe** names the unit under test (component, module, or feature slice).
+- Inner **describe** uses **When [context]** (or equivalent grouping) for the situation.
+- **it** (or **test**) names start with **should** and state one observable outcome.
+
+Dan North (2006): naming tests as sentences keeps focus on the **next behaviour** you care about.
+
+## Soap-opera personas
+
+When you lack full personas, introduce **short-lived characters** with a name and role and deepen them as scenarios grow—like a serial drama adding cast over episodes (Smart & Molak §7.6.5). Embed **\[Name], the \[role]** in scenario titles or setup where the actor changes behavior.
+
+## Example (JavaScript-style)
+
+```javascript
+describe("PaymentProcessor", () => {
+  describe("When Carrie the compliance officer requests a refund for a disputed charge", () => {
+    it("should deduct the refund amount from the account balance", async () => {
+      const disputedChargeAmount = 150.0;
+      const refundResult = await processor.refund(carrieAccountId, disputedChargeAmount);
+      expect(refundResult.status).toBe("completed");
+      expect(refundResult.amount).toBe(disputedChargeAmount);
+    });
+
+    it("should create an audit record with a timestamp and initiator", async () => {
+      const disputedChargeAmount = 150.0;
+      const auditRecord = await processor.refund(carrieAccountId, disputedChargeAmount);
+      expect(auditRecord.timestamp).toBeDefined();
+      expect(auditRecord.initiator).toBe("carrie_compliance");
+    });
+  });
+
+  describe("When Barry the small business owner requests a refund", () => {
+    it("should send a confirmation notification within business hours", async () => {
+      const refundAmount = 500.0;
+      const confirmation = await processor.refund(barryAccountId, refundAmount);
+      expect(confirmation.notificationSent).toBe(true);
+    });
+  });
+});
+```
+
+Adapt naming to your test runner (pytest: functions; Jest/Vitest: `it`; JUnit: `@Test` methods with `should_` names).
+
+## File organization
+
+- Prefer **one file per feature slice** or user journey when it keeps related behaviours together.
+- Split when files grow hard to scan; keep **should** names readable in lists and IDEs.
+
+## Checklist
+
+- [ ] Every test name reads as a **should** sentence for one outcome
+- [ ] Groups use **When**-style context where it helps navigation
+- [ ] Personas appear only when they change behaviour or clarity
+- [ ] Tests do not mirror production folders if that obscures behaviour
+- [ ] A new reader can understand intent without opening production code first
+
+## References
+
+- Smart & Molak, *BDD in Action* 2e, §16.5.5 (test layout), §7.6.5 (personas)
+- Dan North, "Introducing BDD" (2006)

package/hooks/blocking/tdd-enforcer.py

@@ -1,8 +1,8 @@
 #!/usr/bin/env python3
 """
-TDD enforcement hook.
+BDD Automate-phase reminder (production code touch).
 
-Prompts confirmation when writing/editing production code files.
+Prompts confirmation when writing or editing production code files.
 Skips: Test files, config files, documentation.
 """
 import json
@@ -51,7 +51,7 @@ def main() -> None:
         "hookSpecificOutput": {
             "hookEventName": "PreToolUse",
             "permissionDecision": "allow",
-            "additionalContext": "[TDD] Writing production code. Confirm you have a failing test first."
+            "additionalContext": "[BDD] Writing production code. Confirm you have a failing specification (test) first."
         }
     }
     print(json.dumps(result))

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "1.19.3",
+    "version": "1.21.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {
@@ -13,7 +13,10 @@
         "commands/",
         "agents/",
         "skills/",
-        "hooks/"
+        "hooks/",
+        "system-prompts/",
+        "scripts/",
+        "CLAUDE.md"
     ],
     "keywords": [
         "claude-code",

package/rules/bdd.md

@@ -0,0 +1,28 @@
+# BDD (discovery-driven development)
+
+**Canonical detail:** `~/.claude/system-prompts/software-engineer.xml` → `<behavior_protocol>`.
+
+**On-demand depth:** `@~/.claude/skills/bdd-protocol/SKILL.md` (Example Mapping §6.4, §7.6 catalog, solo patterns). Tracking design: [jl-cmd/claude-code-config#82](https://github.com/jl-cmd/claude-code-config/issues/82).
+
+**Optional long-form references (load when needed):**
+
+- `@~/.claude/docs/BDD_SCENARIO_QUALITY.md` — seven scenario quality patterns (§7.6-style)
+- `@~/.claude/docs/BDD_DISCOVERY_PROTOCOL.md` — Example Mapping algorithm for chat
+- `@~/.claude/docs/BDD_TEST_LAYOUT.md` — describe/when/should layout and soap-opera personas
+
+## What you do for every non-trivial feature
+
+1. **Deliberate Discovery** — Reduce uncertainty before code; surface what you do not know (Smart & Molak §5.4).
+2. **Illustrate** — Explore goals, constraints, and concrete examples in chat; "given … when … then …" style outcomes.
+3. **Formulate** — Express behavior as narrow **"should …"** specifications the user can approve.
+4. **Automate** — Failing specification first, then minimum code to pass; refactor only for a concrete smell.
+
+Conversation is the essential practice: if discovery is skipped, structured formats do not rescue the workflow (Minimal BDD).
+
+## Solo developer
+
+You are often the stakeholder. Use **Example Mapping** in chat ("the one where …", probes, parking lot). Load **`bdd-protocol`** when you need the full algorithm and anti-pattern list.
+
+## Naming
+
+Developer-facing specs and tests use **should** sentences so intent stays visible (Dan North, "Introducing BDD", 2006).

package/rules/code-standards.md

@@ -3,7 +3,7 @@
 > **MANDATORY REFERENCE:** CODE_RULES.md - Load for ALL code generation.
 > This is the single source of truth for code standards. Non-negotiable.
 
-@${CLAUDE_PLUGIN_ROOT}/docs/CODE_RULES.md
+@~/.claude/docs/CODE_RULES.md
 
 **Key principles (see CODE_RULES.md for complete reference):**
 - Self-documenting code (no comments)

package/rules/self-contained-docs.md

@@ -0,0 +1,17 @@
+# Self-Contained Documentation
+
+**When this applies:** All generated artifacts — gists, decision docs, PR descriptions, issue bodies, plans, SKILL.md content. Exception: Obsidian session logs (intentionally conversation-scoped).
+
+## Rule
+
+Every document must be fully self-contained. A reader with zero prior context must understand every statement without needing access to the conversation that produced it.
+
+## Patterns to Catch and Replace
+
+| Pattern | Example | Fix |
+|---|---|---|
+| References to options/choices discussed in conversation | "This is not Option A from the original framing" | Delete the sentence, or restate the decision on its own terms |
+| "As discussed" / "as we decided" / "from the prior session" | "As discussed, we'll use embeddings" | "Sref matching uses sentence-transformer embeddings" |
+| Pronouns pointing to conversation context | "This approach addresses the concerns raised earlier" | State what the concerns were inline, or delete |
+| Relative framing ("instead of X") where X was only discussed verbally | "Instead of the three options considered" | State the chosen approach directly without referencing alternatives the reader can't see |
+| Session-specific sequencing | "After Round 3 we decided..." | State the decision as a fact |

package/rules/testing.md

@@ -2,7 +2,7 @@
 
 > **Reference:** TEST_QUALITY.md - Load when writing or reviewing tests.
 
-@${CLAUDE_PLUGIN_ROOT}/docs/TEST_QUALITY.md
+@~/.claude/docs/TEST_QUALITY.md
 
 ## Complete Mocks for Testability
 

package/rules/vault-context.md

@@ -0,0 +1,34 @@
+# Obsidian Vault Context
+
+An Obsidian vault stores session reports, decisions, and research documents across all projects. Its filesystem location is configured per user via the `OBSIDIAN_VAULT_PATH` environment variable (or the equivalent path exposed by the user's Obsidian MCP server). Do not assume a specific OS path; resolve the vault location from the configured MCP tools before reading files directly.
+
+## Available MCP Tools
+
+- `mcp__obsidian__search_notes` -- search by content or frontmatter (`searchFrontmatter: true`)
+- `mcp__obsidian__read_note` -- read a single note by path
+- `mcp__obsidian__read_multiple_notes` -- read several notes at once
+
+## Vault Structure
+
+- `sessions/` -- session reports with frontmatter: `type: session-report`, `project`, `session`, `date`, `status`, `blocked`, `tags`
+- `decisions/` -- decision notes with frontmatter: `type: decision|procedural|fact|gotcha`, `project`, `date`, `status: Active|Superseded`, `tags`
+- `Research/` -- deep research documents
+
+## When to Search
+
+IMPORTANT: Before starting substantive project work, search the vault for prior sessions and decisions for the current project. Also search when:
+- Encountering a component or system with known history
+- A task might repeat or reverse a prior decision
+- You need context on why something was built a certain way
+
+Search by `project` frontmatter field first, then by content keywords like "blocked", "superseded", "decision", "gotcha".
+
+## Session Logging
+
+When the user invokes `/session-log`, treat **short and long sessions the same**: run the full logging flow. Session length does not change the requirements below.
+
+At the end of substantive sessions, offer to run `/session-log` if not already invoked.
+
+When running `/session-log`, include `vault_context_retrieved: true|false` in frontmatter based on whether vault MCP tools were used this session.
+
+After writing a session log, ALWAYS output a `/rename` command with a descriptive session name based on the session's primary outcome. Format: `/rename [Project] - [Primary Outcome]`. This is a mandatory output requirement, not optional.

package/rules/verify-before-asking.md

@@ -0,0 +1,42 @@
+# Verify Before Asking
+
+**When this applies:** Before asking the user any clarifying question during discovery, scoping, or implementation planning.
+
+## Rule
+
+If a question can be answered by inspecting files, running a command, querying a database, reading a config, or using any available tool, answer it yourself. Only ask the user questions that require their judgment, preference, or knowledge that is not accessible to automated inspection.
+
+## Decision Checklist
+
+Before writing any AskUserQuestion or asking a clarifying question in chat, evaluate:
+
+| Check | Action |
+|---|---|
+| Does the answer live in a file on disk? | Read the file. |
+| Does the answer live in a directory structure? | List the directory. |
+| Does the answer live in a database? | Query the database. |
+| Does the answer live in git history? | Run `git log` or `git blame`. |
+| Is the answer determined by file naming patterns or contents? | Glob a sample and inspect. |
+| Is the answer a value in a config or environment variable? | Read the config or check the env. |
+| Is the answer retrievable from any available MCP tool? | Use the tool. |
+
+Only after confirming the answer cannot be obtained through any available tool, ask the user.
+
+## Questions That Belong to the User
+
+Reserve user questions for:
+- **Preferences** — "Do you want approach A or B?" when both are viable and the user has a stake.
+- **Missing context the user holds** — passwords, account names, intent, future plans.
+- **Judgment calls** — tradeoffs the user needs to evaluate.
+- **Scope decisions** — what to include or exclude from a piece of work.
+
+## Examples
+
+**Wrong:** "Are there multiple images per folder, or just one image + one mp4?"
+**Right:** List the folder contents directly, then state what was found.
+
+**Wrong:** "What columns does the themes table have?"
+**Right:** Query `information_schema.columns` and report the schema.
+
+**Wrong:** "Is there a Prisma schema in this project?"
+**Right:** Glob for `schema.prisma` and check.

package/scripts/sync-to-cursor.py

@@ -0,0 +1,22 @@
+#!/usr/bin/env python3
+"""Generate Cursor rules from ~/.claude/rules and docs.
+
+Writes to <profile or repo>/.cursor/rules/*.mdc, .cursor/docs/*.md (byte copies of
+CODE_RULES.md and TEST_QUALITY.md when present), and .cursor/.sync-manifest.json.
+If LLM_SETTINGS_ROOT is set to the llm-settings repo root, uses <root>/.claude and
+<root>/.cursor. Otherwise uses ~/.claude and ~/.cursor (after junction install).
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+_SCRIPTS_DIR = Path(__file__).resolve().parent
+if str(_SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIR))
+
+from sync_to_cursor.engine import main
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/sync_to_cursor/__init__.py

@@ -0,0 +1,13 @@
+"""Sync Claude ~/.claude rules and docs into Cursor .cursor layout."""
+
+from sync_to_cursor.config import MAX_RULE_BODY_LINES
+from sync_to_cursor.canonical_docs import sync_canonical_docs as _sync_canonical_docs
+from sync_to_cursor.rules import _limit_lines, merge_code_standards, merge_test_quality
+
+__all__ = [
+    "MAX_RULE_BODY_LINES",
+    "_limit_lines",
+    "_sync_canonical_docs",
+    "merge_code_standards",
+    "merge_test_quality",
+]

package/scripts/sync_to_cursor/canonical_docs.py

@@ -0,0 +1,66 @@
+"""Copy and verify canonical docs under .cursor/docs/."""
+
+import shutil
+from pathlib import Path
+
+from sync_to_cursor.config import CANONICAL_DOC_FILES
+from sync_to_cursor.hashing import sha256_bytes
+
+
+def sync_canonical_docs(
+    claude: Path,
+    cursor: Path,
+    dry_run: bool,
+    quiet: bool,
+) -> dict:
+    docs_out = cursor / "docs"
+    if not dry_run:
+        docs_out.mkdir(parents=True, exist_ok=True)
+    new_docs: dict = {}
+    for name in CANONICAL_DOC_FILES:
+        src = claude / "docs" / name
+        dst = docs_out / name
+        if not src.is_file():
+            if dst.is_file():
+                if not dry_run:
+                    dst.unlink()
+                if not quiet:
+                    print(f"WARN     docs/{name} (source removed — deleted stale copy at {dst})")
+            elif not quiet:
+                print(f"WARN     docs/{name} (missing source: {src})")
+            continue
+        key = f"docs/{name}"
+        src_hash = sha256_bytes(src.read_bytes())
+        if dry_run:
+            if dst.is_file():
+                out_hash = sha256_bytes(dst.read_bytes())
+            else:
+                out_hash = ""
+        else:
+            shutil.copy2(src, dst)
+            out_hash = sha256_bytes(dst.read_bytes())
+        new_docs[key] = {"sources_hash": src_hash, "output_hash": out_hash}
+    return new_docs
+
+
+def check_canonical_docs(claude: Path, cursor: Path, docs_entries: dict) -> bool:
+    for name in CANONICAL_DOC_FILES:
+        key = f"docs/{name}"
+        src = claude / "docs" / name
+        dst = cursor / "docs" / name
+        if not src.is_file():
+            if key in docs_entries:
+                return False
+            continue
+        if not dst.is_file():
+            return False
+        src_hash = sha256_bytes(src.read_bytes())
+        dst_hash = sha256_bytes(dst.read_bytes())
+        prev = docs_entries.get(key)
+        if not prev:
+            return False
+        if prev.get("sources_hash") != src_hash:
+            return False
+        if prev.get("output_hash") != dst_hash:
+            return False
+    return True

package/scripts/sync_to_cursor/config.py

@@ -0,0 +1,5 @@
+"""Shared configuration for the sync-to-cursor package."""
+
+GENERATOR_VERSION: str = "1.2.3"
+CANONICAL_DOC_FILES: tuple[str, ...] = ("CODE_RULES.md", "TEST_QUALITY.md")
+MAX_RULE_BODY_LINES: int = 50