claude-dev-env 1.19.3 → 1.20.1

package/rules/code-standards.md

@@ -1,43 +1 @@
-# Code Standards
-
-> **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
-
-**Key principles (see CODE_RULES.md for complete reference):**
-- Self-documenting code (no comments)
-- Centralized configuration (one source of truth)
-- Reuse constants (search before creating)
-- No magic values (everything named)
-- No abbreviations (full words)
-- Complete type hints
-- TDD (test first)
-
-## Function Parameters - Required vs Optional
-
-**Use required parameters when no valid use case exists for optional.**
-**Remove unused parameters.**
-
-## Encapsulation - Logic Belongs in Models
-
-**NEVER scatter construction logic in calling code.**
-
-Path/URL building, formatting, transformations -> Put in model methods.
-If you find yourself building the same string pattern in multiple places, it belongs in the model.
-
-## Document Temporary Code
-
-**Scaffolding/placeholder code MUST have TODO comments.**
-
-When code exists only to enable testing before full implementation:
-- Add `// TODO: Replace with...` explaining what will replace it
-- Explain WHY it's temporary, not just WHAT it does
-
-## Naming Reflects Behavior
-
-**Name components after what they ARE, not abstract concepts.**
-
-If it overlays the viewport -> "Overlay" not "Screen"
-If it validates input -> "Validator" not "Handler"
-Names should describe observable behavior or visual appearance.
+# Code-standards pointer: canonical policy lives in `~/.claude/system-prompts/software-engineer.xml` under `<code_quality>`.

package/rules/conservative-action.md

@@ -1,20 +1 @@
-# Conservative Action
-
-Source: [Anthropic - Tool Usage](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#tool-usage)
-
-<do_not_act_before_instructions>
-When the user's intent is ambiguous, default to research and recommendations rather than taking action. Provide information, explain options, and surface tradeoffs — then let the user decide before making changes.
-
-Proceed with edits, file modifications, or implementations only when the user explicitly requests them.
-</do_not_act_before_instructions>
-
-## Deciding whether to act
-
-- If the user asks a question, answer the question. Do not also fix the thing they asked about.
-- If the user describes a problem, investigate and recommend. Do not jump to implementation.
-- If the user says "do it", "go ahead", "make the change", or similarly explicit language, proceed with action.
-- When in doubt, ask: "Would you like me to make this change, or just show you the approach?"
-
-## Why
-
-Acting prematurely wastes effort and round-trips when the user wanted a different approach. Exploring first produces better outcomes than committing early. This is especially important with models that have a strong action bias.
+# Conservative-action pointer: canonical policy lives in `~/.claude/system-prompts/software-engineer.xml` under `<task_scope>`.

package/rules/context7.md

@@ -1,12 +1 @@
----
-alwaysApply: true
----
-
-When working with libraries, frameworks, or APIs — use Context7 MCP to fetch current documentation instead of relying on training data. This includes setup questions, code generation, API references, and anything involving specific packages.
-
-## Steps
-
-1. Call `resolve-library-id` with the library name and the user's question
-2. Pick the best match — prefer exact names and version-specific IDs when a version is mentioned
-3. Call `query-docs` with the selected library ID and the user's question
-4. Answer using the fetched docs — include code examples and cite the version
+# Context7 pointer: canonical policy lives in `~/.claude/system-prompts/software-engineer.xml` under `<context7>`.

package/rules/explore-thoroughly.md

@@ -1,27 +1 @@
-# Explore Thoroughly
-
-Source: [Anthropic - Overthinking and Excessive Thoroughness](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#overthinking-and-excessive-thoroughness)
-
-Note: This deliberately chooses exploration depth over the "commit and execute quickly" pattern from the same source. Thorough upfront exploration is preferred for the intended workflow.
-
-## Before committing to an approach
-
-- Read the relevant files. Understand what exists before proposing what to change.
-- Map the existing patterns: naming conventions, file organization, architectural decisions.
-- Identify constraints that could invalidate an approach before investing effort in it.
-- For unfamiliar codebases or high-stakes changes, invest more time exploring than feels necessary.
-
-## Exploration scales with risk
-
-- Small change to a familiar file: a quick read of the file and its immediate neighbors is sufficient.
-- New feature or cross-cutting change: read broadly across the codebase to understand how similar things are done.
-- Architectural decision: explore the full landscape before recommending a direction.
-
-## Relationship to other rules
-
-- **conservative-action.md** gates *whether* to act. This rule governs *how deeply* to investigate.
-- **research-mode.md** ensures factual claims are grounded. This rule ensures implementation plans are grounded in the actual codebase.
-
-## Why
-
-Premature commitment leads to wasted effort when the chosen approach conflicts with existing patterns or misses important context. Thorough exploration surfaces constraints early and produces better-informed solutions.
+# Explore-thoroughly pointer: canonical policy lives in `~/.claude/system-prompts/software-engineer.xml` under `<investigation>`.

package/rules/git-workflow.md

@@ -1,42 +1 @@
-# Git Workflow
-
-User-level rule: applies to **every** git repo that uses GitHub with `gh` (no exceptions for “small” or non-primary repos unless the user says otherwise in the session).
-
-## Workflow Decision Tree
-
-**When to use stacked PRs:** Feature B depends on Feature A's implementation
-
-**When to extract shared infrastructure first:** Multiple features need same utilities/helpers
-
-**Extract Shared Infrastructure Pattern:**
-1. Create infrastructure PR with only shared code
-2. Get reviewed and MERGE infrastructure first
-3. Launch parallel feature PRs that use merged infrastructure
-
-## PR Submission Rules
-
-**ALWAYS create PRs as DRAFT:** Use `gh pr create --draft` for ALL PRs
-
-## Git Golden Rules (NON-NEGOTIABLE)
-
-1. **DRAFT BEFORE PUSH**: When pushing ANYTHING to a PR, it MUST be in draft state first
-   - Before push: `gh pr ready --undo`
-   - After review approved: `gh pr ready`
-
-2. **ONE COMMIT PER REVIEW STAGE**: Each review round gets exactly ONE commit
-   - Initial feature: 1 commit
-   - After review #1: 2 commits (initial + review #1 fixes)
-   - After review #2: 3 commits (initial + review #1 fixes + review #2 fixes)
-   - NEVER squash multiple review stages into one commit
-   - NEVER have multiple commits for the same review stage
-
-## Never Commit Working Documents or Images
-
-**NEVER commit these files to the repo:**
-
-| Pattern | Reason |
-|---------|--------|
-| `docs/plans/*.md` | Working documents for planning, not repo content |
-| `*.plan.md` | Temporary planning files |
-| `SESSION_STATE.md` | Local session state |
-| `*.png *.jpg *.jpeg *.gif *.webp *.avif *.svg *.ico` | Images go to external storage, not GitHub |
+# Git-workflow pointer: canonical git workflow policy lives in `~/.claude/system-prompts/software-engineer.xml` under `<git_workflow>`.

package/rules/parallel-tools.md

@@ -1,23 +1 @@
-# Parallel Tool Calls
-
-Source: [Anthropic - Parallel Tool Calling](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#optimize-parallel-tool-calling)
-
-<use_parallel_tool_calls>
-When multiple tool calls have no dependencies between them, make all independent calls in a single response. Only sequence calls when a later call needs an earlier call's result.
-</use_parallel_tool_calls>
-
-## Examples
-
-- Reading 3 files: call all 3 Read operations at once.
-- Running independent searches: launch all Grep/Glob calls simultaneously.
-- Checking git status + reading a config file: both in one response.
-- Reading a file, then editing based on its content: sequential (edit depends on read result).
-
-## Guard rails
-
-- Use real parameter values only. Do not guess or use placeholders to force parallelism.
-- If you are unsure whether calls are independent, run them sequentially.
-
-## Why
-
-Explicit reinforcement of parallel calling boosts compliance to near 100%. Sequential calls for independent operations waste time and round-trips for the user.
+# Parallel-tools pointer: canonical policy lives in `~/.claude/system-prompts/software-engineer.xml` under `<agent_workflow>`.

package/rules/research-mode.md

@@ -1,23 +1 @@
-# Research Mode (Global)
-
-Three anti-hallucination constraints are ALWAYS active.
-
-Source: [Anthropic - Reduce Hallucinations](https://docs.anthropic.com/en/docs/test-and-evaluate/strengthen-guardrails/reduce-hallucinations)
-
-## 1. Say "I don't know"
-If you don't have a credible source for a claim, say so. Don't guess. Don't infer. "I don't have data on this" is always a valid answer.
-
-## 2. Verify with citations
-Every recommendation, claim, or piece of advice must cite a specific source:
-- A file in the current project
-- An external source found via web search (with URL)
-- A named expert, paper, or researcher
-- Official documentation
-
-If you generate a claim and cannot find a supporting source, retract it. Do not present it.
-
-## 3. Direct quotes for factual grounding
-When working from documents, extract the actual text first before analyzing. Ground your response in word-for-word quotes, not paraphrased summaries. Reference the quote when making your point.
-
-## Exceptions
-Creative thinking, brainstorming, and novel ideas don't require citation. You can synthesize across sources to reach new conclusions, but the inputs must be grounded.
+# Research-mode pointer: canonical policy lives in `~/.claude/system-prompts/software-engineer.xml` under `<investigation>`.

package/rules/right-sized-engineering.md

@@ -1,28 +1 @@
-# Right-Sized Engineering
-
-**Build it right, but build it simple.** Good engineering principles at the appropriate scale.
-
-## Always Do
-- Extract constants and configuration (no hardcoding)
-- Create reusable functions (no copy-paste)
-- Use proper error handling
-- Follow DRY from the start
-- Single responsibility per function
-
-## Never Do (Solo Scale)
-- Abstract base classes for single implementations
-- Dependency injection frameworks
-- Complex patterns (CQRS, microservices)
-- Multiple inheritance hierarchies
-- Over-abstracted interfaces
-
-## Complexity Budget
-
-**State BEFORE implementation:** Files (target 1-2, max 3), Lines (~50-300), Checkpoints ("Is this MINIMUM?", "Fewer files?", "Functions vs classes?")
-
-## YAGNI for API Surface
-
-**Don't expose optional parameters until they're actually used.**
-
-If a value will always be a constant for now, use the constant internally.
-Only add the parameter when callers actually need to vary it.
+# Right-sized-engineering pointer: canonical policy lives in `~/.claude/system-prompts/software-engineer.xml` under `<scope_discipline>`.

package/rules/self-contained-docs.md

@@ -0,0 +1 @@
+# Self-contained-docs pointer: canonical policy lives in `~/.claude/system-prompts/software-engineer.xml` under `<documentation>`.

package/rules/vault-context.md

@@ -0,0 +1 @@
+# Vault-context pointer: canonical policy lives in `~/.claude/system-prompts/software-engineer.xml` under `<obsidian_vault>`.

package/rules/verify-before-asking.md

@@ -0,0 +1 @@
+# Verify-before-asking pointer: canonical policy lives in `~/.claude/system-prompts/software-engineer.xml` under `<investigation>`.

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

package/scripts/sync_to_cursor/engine.py

@@ -0,0 +1,194 @@
+"""Sync Claude rules to Cursor .mdc files and manifest."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+from sync_to_cursor.canonical_docs import check_canonical_docs, sync_canonical_docs
+from sync_to_cursor.config import GENERATOR_VERSION
+from sync_to_cursor.hashing import sha256_bytes
+from sync_to_cursor.paths import llm_layout_paths
+from sync_to_cursor.rules import RuleMapping, _full_mdc, apply_transform, build_mappings
+
+
+def _load_manifest(manifest_path: Path) -> dict:
+    if not manifest_path.is_file():
+        return {}
+    try:
+        return json.loads(manifest_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return {}
+
+
+def _sources_hash(paths: tuple[Path, ...]) -> str:
+    return sha256_bytes(b"\x00".join(p.read_bytes() for p in paths))
+
+
+def _run_check(
+    mappings: tuple[RuleMapping, ...],
+    out_dir: Path,
+    entries_meta: dict,
+    claude: Path,
+    cursor: Path,
+    docs_entries_meta: dict,
+) -> int:
+    for each_mapping in mappings:
+        key = f"rules/{each_mapping.output_name}"
+        out_path = out_dir / each_mapping.output_name
+        missing = [source for source in each_mapping.sources if not source.is_file()]
+        if missing:
+            if each_mapping.always_apply:
+                return 1
+            continue
+        src_hash = _sources_hash(each_mapping.sources)
+        prev = entries_meta.get(key, {})
+        if src_hash != prev.get("sources_hash"):
+            return 1
+        prev_out = prev.get("output_hash", "")
+        if out_path.is_file() and prev_out:
+            if sha256_bytes(out_path.read_bytes()) != prev_out:
+                return 1
+        elif not out_path.is_file():
+            return 1
+    if out_dir.is_dir():
+        for each_path in out_dir.glob("*.mdc"):
+            if each_path.name not in {x.output_name for x in mappings}:
+                return 1
+    if not check_canonical_docs(claude, cursor, docs_entries_meta):
+        return 1
+    return 0
+
+
+def _sync_rules(
+    mappings: tuple[RuleMapping, ...],
+    out_dir: Path,
+    entries_meta: dict,
+    *,
+    force: bool,
+    dry_run: bool,
+    quiet: bool,
+    cursor: Path,
+) -> tuple[dict, dict]:
+    summary: dict = {"skip": 0, "update": 0, "tampered": 0, "warn": 0, "orphan": 0}
+    new_entries: dict = {}
+    write_allowed = not dry_run
+
+    for each_mapping in mappings:
+        key = f"rules/{each_mapping.output_name}"
+        out_path = out_dir / each_mapping.output_name
+        missing = [source for source in each_mapping.sources if not source.is_file()]
+        if missing:
+            summary["warn"] += 1
+            if not quiet:
+                print(f"WARN     rules/{each_mapping.output_name} (missing source: {missing})")
+            continue
+
+        src_hash = _sources_hash(each_mapping.sources)
+        prev = entries_meta.get(key, {})
+        prev_src = prev.get("sources_hash", "")
+        prev_out = prev.get("output_hash", "")
+
+        if (
+            not force
+            and out_path.is_file()
+            and prev_src == src_hash
+            and prev_out
+            and sha256_bytes(out_path.read_bytes()) == prev_out
+        ):
+            summary["skip"] += 1
+            new_entries[key] = {"sources_hash": src_hash, "output_hash": prev_out}
+            continue
+
+        if (
+            not force
+            and out_path.is_file()
+            and prev_src == src_hash
+            and prev_out
+            and sha256_bytes(out_path.read_bytes()) != prev_out
+        ):
+            summary["tampered"] += 1
+            if not quiet:
+                print(f"TAMPERED rules/{each_mapping.output_name} (manual edit; regenerating)")
+
+        summary["update"] += 1
+        if not quiet:
+            print(f"UPDATE   rules/{each_mapping.output_name}")
+
+        body = apply_transform(
+            each_mapping.transform,
+            each_mapping.sources,
+            strip_leading_frontmatter=each_mapping.strip_leading_frontmatter,
+        )
+        full = _full_mdc(each_mapping, body)
+        out_hash = sha256_bytes(full.encode("utf-8"))
+        new_entries[key] = {"sources_hash": src_hash, "output_hash": out_hash}
+
+        if write_allowed:
+            out_path.write_text(full, encoding="utf-8", newline="\n")
+
+    expected = {each_mapping.output_name for each_mapping in mappings}
+    for each_path in out_dir.glob("*.mdc"):
+        if each_path.name not in expected:
+            summary["orphan"] += 1
+            if not quiet:
+                print(f"WARN     {each_path.relative_to(cursor)} (orphan — not generated by this tool)")
+
+    return summary, new_entries
+
+
+def run(argv: list[str] | None = None) -> int:
+    argument_parser = argparse.ArgumentParser(description="Sync Claude rules to Cursor .mdc files")
+    argument_parser.add_argument("--force", action="store_true", help="Regenerate all outputs")
+    argument_parser.add_argument("--dry-run", action="store_true", help="Print actions only")
+    argument_parser.add_argument("--check", action="store_true", help="Exit 1 if anything stale")
+    argument_parser.add_argument("--quiet", action="store_true", help="Minimal output when up to date")
+    args = argument_parser.parse_args(argv)
+
+    claude, cursor, out_dir, manifest_path = llm_layout_paths()
+    mappings = build_mappings(claude)
+    old_manifest = _load_manifest(manifest_path)
+    entries_meta: dict = old_manifest.get("entries", {})
+    docs_entries_meta: dict = old_manifest.get("docs_entries", {})
+
+    if args.check:
+        return _run_check(mappings, out_dir, entries_meta, claude, cursor, docs_entries_meta)
+
+    if not args.dry_run:
+        out_dir.mkdir(parents=True, exist_ok=True)
+    new_docs_entries = sync_canonical_docs(claude, cursor, args.dry_run, args.quiet)
+
+    summary, new_entries = _sync_rules(
+        mappings,
+        out_dir,
+        entries_meta,
+        force=args.force,
+        dry_run=args.dry_run,
+        quiet=args.quiet,
+        cursor=cursor,
+    )
+
+    manifest_out = {
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "generator_version": GENERATOR_VERSION,
+        "entries": new_entries,
+        "docs_entries": new_docs_entries,
+    }
+    if not args.dry_run:
+        manifest_path.write_text(json.dumps(manifest_out, indent=2) + "\n", encoding="utf-8")
+
+    if (
+        not args.quiet
+        and summary["skip"]
+        and not any((summary["update"], summary["tampered"], summary["warn"], summary["orphan"]))
+    ):
+        print(f"SKIP     all {summary['skip']} rule(s) unchanged")
+
+    return 0
+
+
+def main() -> int:
+    return run(sys.argv[1:])

package/scripts/sync_to_cursor/hashing.py

@@ -0,0 +1,7 @@
+"""Content hashing for manifest entries."""
+
+import hashlib
+
+
+def sha256_bytes(content_bytes: bytes) -> str:
+    return hashlib.sha256(content_bytes).hexdigest()

package/scripts/sync_to_cursor/paths.py

@@ -0,0 +1,18 @@
+"""Resolve Claude / Cursor layout paths (LLM_SETTINGS_ROOT or home)."""
+
+import os
+from pathlib import Path
+
+
+def llm_layout_paths() -> tuple[Path, Path, Path, Path]:
+    """Return (claude_dir, cursor_dir, rules_out_dir, manifest_path)."""
+    raw = os.environ.get("LLM_SETTINGS_ROOT", "").strip()
+    if raw:
+        base = Path(raw).expanduser().resolve()
+        claude = base / ".claude"
+        cursor = base / ".cursor"
+    else:
+        home = Path.home()
+        claude = home / ".claude"
+        cursor = home / ".cursor"
+    return claude, cursor, cursor / "rules", cursor / ".sync-manifest.json"