claude-dev-env 1.20.1 → 1.21.0

package/CLAUDE.md

@@ -1,16 +1,43 @@
 # Claude Development Assistant
 
-Canonical behavior policy lives in `~/.claude/system-prompts/software-engineer.xml`.
+## Code Rules (NON-NEGOTIABLE)
+@~/.claude/docs/CODE_RULES.md
 
-## Canonical Pointers
+## Core Philosophy
 
-- Code quality rules: `~/.claude/docs/CODE_RULES.md` (pointer to `<code_quality>`)
-- Git workflow: `~/.claude/rules/git-workflow.md` (pointer to `<git_workflow>`)
-- Development protocol: `<behavior_protocol>` in the system prompt; lean rule `~/.claude/rules/bdd.md`; on-demand `bdd-protocol` skill
-- Tool usage and workflow: `<tool_usage>` and `<agent_workflow>` in the system prompt
+**TDD IS NON-NEGOTIABLE.** Build it right, build it simple. Maintainable > Clever.
 
-## Additional Non-overlapping Rules
+## Working with Claude
 
-- Prompt workflow controls: `@~/.claude/rules/prompt-workflow-context-controls.md`
-- Testing quality specifics: `@~/.claude/rules/testing.md`
-- Path-scoped Tasklings preferences load automatically via `~/.claude/rules/tasklings-preferences.md`
+### 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/docs/CODE_RULES.md

@@ -1 +1,208 @@
-# CODE_RULES pointer: canonical code-quality policy lives in `~/.claude/system-prompts/software-engineer.xml` under `<code_quality>`.
+# Code Rules Reference
+
+Compact reference for agents. Hook-enforced rules marked with ⚡.
+
+---
+
+## COMMENT PRESERVATION (ABSOLUTE RULE)
+
+**NEVER remove existing comments.** If you are not adding or removing code on a line, do not touch its comments.
+
+- Existing comments are SACRED — never delete, rewrite, or "clean up" existing comments
+- New inline comments are not needed — write self-documenting code instead
+- Docstrings for new files/methods/classes are allowed
+- The hook enforces BOTH directions: blocks new inline comments AND blocks deletion of existing comments
+
+**Scope:** Only evaluate comments on lines YOU are actively changing. If code is untouched, its comments are untouched.
+
+---
+
+## CORE PRINCIPLES
+
+### Self-Documenting Code
+New code explains itself through naming. Do not add new inline comments — use descriptive names instead. Docstrings on functions/methods/classes are allowed.
+
+> **Full readability standard:** `~/.claude/skills/readability-review/SKILL.md` — 8-dimension rubric (naming, SRP, abstraction, control flow, domain language, call sites, state clarity, visual rhythm). Run `/check` for parallel team review or `/readability-review` standalone.
+
+### Centralized Configuration
+One source of truth. Every constant lives in ONE place (`config/`).
+
+### Reuse Before Create
+Search first. Import second. Create last.
+
+### Encapsulation Enables Cleaner Naming
+Expose constants via helper functions: `isMaxLevel(level)` > `level >= MAXIMUM_LEVEL`
+
+---
+
+## ⚡ HOOK-ENFORCED RULES
+
+These rules are automatically enforced by `code-rules-enforcer.py`. Violations block Write/Edit.
+
+| Rule | What's Checked |
+|------|----------------|
+| No NEW comments | `#` / `//` in new code only (existing comments NEVER removed; shebangs, type:, noqa, eslint, docstrings exempt) |
+| Imports at top | No `import` inside function bodies |
+| Logging format args | No `log_*(f"...")` - use `log_*("...", arg)` |
+| File line count | Advisory only — see [File length guidance](#65-file-length-guidance) |
+| Magic values | No literals in function bodies (0, 1, -1 exempt). Includes string templates — if you strip the interpolations from an f-string and the remaining literal text is structural (paths, URLs, patterns), those fragments are magic values that belong in config |
+| Constants location | No `UPPER_SNAKE =` outside `config/` |
+
+---
+
+## 3. REUSE CONSTANTS (DRY CONFIG)
+
+**Before writing ANY constant:**
+
+```bash
+# Find config files
+# Search your project for existing config files before creating new ones
+
+# Search for value
+grep -r "VALUE" config/
+```
+
+**Decision tree:**
+1. Search exact value → Found? → IMPORT IT
+2. Search semantic match → Found? → USE EXISTING NAME
+3. Config file exists? → ADD TO EXISTING
+4. Create new (rare)
+
+---
+
+## 4. CONFIG LOCATIONS
+
+| Constant Type | Location |
+|---------------|----------|
+| Timeouts, delays, retries | `config/timing.py` |
+| Ports, URLs, thresholds | `config/constants.py` |
+| CSS selectors | `config/selectors.py` |
+
+---
+
+## 5. NO ABBREVIATIONS
+
+Full words only. No mental translation.
+
+| Bad | Good |
+|-----|------|
+| `ctx`, `cfg`, `msg` | `context`, `configuration`, `message` |
+| `btn`, `idx`, `cnt` | `button`, `index`, `count` |
+| `tmp`, `elem`, `val` | `temporary_value`, `element`, `value` |
+
+**Exception:** `i`, `j`, `k` in loops; `e` for exception.
+
+**Extended naming rules** (from readability-review rubric):
+- Loop vars: `each_order`, `each_user` (prefix `each_`)
+- Booleans: `is_valid`, `has_permission`, `should_retry` (prefix `is_`/`has_`/`should_`/`can_`)
+- Collections: `all_orders`, `all_users` (prefix `all_`)
+- Maps: `price_by_product`, `user_by_id` (pattern `X_by_Y`)
+- Preposition params: `from_path=`, `to=`, `into=`
+- **Banned names:** `result`, `data`, `output`, `response`, `value`, `item`, `temp`
+- **Banned prefixes:** `handle`, `process`, `manage`, `do`
+
+---
+
+## 6. COMPLETE TYPE HINTS
+
+```python
+def function_name(
+    parameter: str,
+    optional: Optional[str] = None,
+) -> ReturnType:
+```
+
+- ALL parameters typed
+- ALL returns typed
+- No `Any` type
+- No `# type: ignore`
+
+*(Also enforced by mypy_validator.py hook)*
+
+---
+
+## 6.5 FILE LENGTH GUIDANCE
+
+File length is a **smell signal, not a hard threshold**. Long files often hide multiple responsibilities, but legitimately long files exist (migrations, generated code, registries, fixtures). The hook surfaces advisories instead of blocking.
+
+**Two advisory thresholds (non-blocking, stderr only):**
+
+| Threshold | Source basis | Hook behavior |
+|-----------|--------------|---------------|
+| `>= 400` lines | Robert C. Martin, *Clean Code* (2008), Ch. 5 "Formatting" — small files preferred; Martin Fowler, *Refactoring* — "Large Class" code smell | Soft advisory: "consider splitting" |
+| `>= 1000` lines | pylint default `max-module-lines=1000`; SonarQube rule S104 default `1000` | Strong nudge: "exceeds widely-used static-analysis defaults" |
+
+**What we deliberately reject:**
+
+- **Hard numeric blocks** — Google's Python Style Guide imposes no file-length cap (only a ~40-line function review hint at https://google.github.io/styleguide/pyguide.html). A blocking rule produces false positives on legitimate cases.
+- **A single magic number** — Different sources land at 200 (*Clean Code* preference), 750 (some SonarQube language profiles), or 1000 (pylint, Sonar Java). No source justifies a single universal cap.
+
+**When to actually split:**
+
+The size signal matters *because* of what it usually indicates: multiple responsibilities (Single Responsibility Principle — Robert C. Martin, *Agile Software Development*, 2002), poor cohesion (Steve McConnell, *Code Complete 2e*, 2004, Ch. 5–6), or the "Large Class" / "Long Function" smells (Fowler). Use the readability rubric (`~/.claude/skills/readability-review/SKILL.md`) when an advisory fires — split based on cohesion, not line count.
+
+---
+
+## 7. RIGHT-SIZED ENGINEERING
+
+**Simple > Clever. Functions > Classes. Concrete > Abstract.**
+
+Never: ABC for single impl, DI frameworks, factory for single type
+Always: Functions when no state, concrete classes, simple imports
+
+---
+
+## 8. TDD PROCESS
+
+1. **RED** - Failing test first
+2. **GREEN** - Minimum code to pass
+3. **REFACTOR** - Only if valuable
+
+---
+
+## 9. SELF-CONTAINED COMPONENTS
+
+Components own their complete feature. Parents just render `<Child />`.
+
+Child handles: state, modals, overlays, toasts
+Parent knows: nothing about child's internals
+
+---
+
+## 10. NO REDUNDANT DATA FETCHES
+
+If you already have data, don't fetch again.
+
+```typescript
+// BAD
+const profile = await getProfile();
+const localProfile = await db.profile.first(); // same data!
+
+// GOOD
+const profile = await db.profile.first();
+// ... use profile throughout ...
+```
+
+---
+
+## QUICK CHECKLIST
+
+```
+Before ANY code:
+[ ] Searched existing configs?
+[ ] Importing from centralized config?
+
+Hook will enforce:
+[⚡] No NEW comments (existing comments NEVER removed)
+[⚡] No magic values
+[⚡] Imports at top
+[⚡] Logging format args
+[ ] File length reasonable (advisory at 400, strong nudge at 1000 — see §6.5)
+[⚡] Constants in config/
+
+Manual check:
+[ ] No abbreviations?
+[ ] Complete type hints?
+[ ] Self-contained components?
+[ ] Readability: /check or /readability-review
+```

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "1.20.1",
+    "version": "1.21.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/rules/agent-spawn-protocol.md

@@ -1 +1,47 @@
-# Agent-spawn-protocol pointer: canonical policy lives in `~/.claude/system-prompts/software-engineer.xml` under `<agent_workflow>`.
+# Agent Spawn Protocol (Mandatory)
+
+**When this applies:** Before any Agent or Task tool invocation (Explore, implementation, research, or team subagents).
+
+<agent_spawn_protocol>
+
+## Before spawning ANY agent — no exceptions
+
+Every Agent and Task tool call must follow this protocol. This includes Explore agents, research agents, execution agents, and team members.
+
+### Step 1: Context sufficiency check
+
+Before writing any agent prompt, verify you can answer all of these:
+- [ ] What specific files, directories, or areas of the codebase are involved?
+- [ ] What constraints apply? (patterns to follow, things NOT to change, boundaries)
+- [ ] What does success look like? (expected output, acceptance criteria)
+- [ ] Is the task unambiguous enough to delegate?
+
+If ANY answer is "I don't know" -- investigate first (read files, search code) or ask the user. Do NOT spawn with incomplete context.
+
+### Step 2: Craft the prompt with /prompt-generator
+
+Run the `/prompt-generator` skill to produce a structured prompt. Feed it:
+- The task description and goal
+- Target files/directories discovered in Step 1
+- Constraints and boundaries
+- Expected output format
+- Acceptance criteria
+
+The skill will ask 1-3 clarifying questions if information is missing -- this is the built-in context verification.
+
+Use the skill's output as the agent's `prompt` parameter.
+
+### Step 3: Spawn the agent
+
+Pass the structured prompt from Step 2 to the Agent/Task tool.
+
+</agent_spawn_protocol>
+
+## Why
+
+Agents receiving vague prompts waste tokens exploring in circles, produce code that misses constraints, and require expensive rework. A 30-second investment in prompt quality via /prompt-generator saves 5-minute agent failures. This applies equally to Explore agents (which waste context on unfocused searches) and execution agents (which write wrong code).
+
+## Relationship to other rules
+
+- **conservative-action.md** gates acting when ambiguous. This extends that: do not delegate when the task is ambiguous—investigate or ask the user first.
+- Project-specific rules or `~/.claude/CLAUDE.md` may define *whether* to use subagents or teams; this rule governs *how* to craft prompts when you do delegate.

package/rules/cleanup-temp-files.md

@@ -1 +1,27 @@
-# Cleanup-temp-files pointer: canonical policy lives in `~/.claude/system-prompts/software-engineer.xml` under `<cleanup>`.
+# Clean Up Temporary Files
+
+**When this applies:** After tasks that created scratch files, debug dumps, or one-off scripts the user did not ask to keep.
+
+Source: [Anthropic — Reduce file creation in agentic coding](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#reduce-file-creation-in-agentic-coding)
+
+## During a task
+
+- Prefer working in memory over creating scratchpad files. Use variables and tool results instead of writing intermediate data to disk.
+- When a temporary file is genuinely needed (e.g., a helper script, a test fixture, a debug output), track it mentally for cleanup.
+
+## When a task is complete
+
+- Remove every temporary file, script, or helper file you created during the task.
+- Leave the working directory cleaner than you found it.
+- If a file was created at the user's explicit request (not as a byproduct of your process), leave it in place.
+
+## What counts as temporary
+
+- Scripts written to test a hypothesis or run a one-off check
+- Debug output files, log dumps, or intermediate data exports
+- Helper files created to work around tool limitations
+- Any file the user did not ask for and would not expect to find after the task
+
+## Why
+
+Temporary files accumulate across sessions and clutter the project root. Latest models sometimes use files as scratchpads during iteration, and these leftovers confuse both the user and future sessions if not cleaned up.

package/rules/code-reviews.md

@@ -1 +1,11 @@
-# Code-reviews pointer: canonical policy lives in `~/.claude/system-prompts/software-engineer.xml` under `<code_review_response>`.
+# Responding to Code Reviews
+
+**When this applies:** GitHub PR review feedback on a branch you are fixing.
+
+**MANDATORY PROTOCOL (use pr-review-responder skill):**
+
+1. Fetch ALL reviewer comments BEFORE any fixes
+2. Create TodoWrite checklist - One item per comment
+3. Fix systematically - Mark each todo complete
+4. Reply to EACH comment inline
+5. Create ONE review fix commit - DO NOT squash with original

package/rules/code-standards.md

@@ -1 +1,43 @@
-# Code-standards pointer: canonical policy lives in `~/.claude/system-prompts/software-engineer.xml` under `<code_quality>`.
+# 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/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.

package/rules/conservative-action.md

@@ -1 +1,20 @@
-# Conservative-action pointer: canonical policy lives in `~/.claude/system-prompts/software-engineer.xml` under `<task_scope>`.
+# 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.

package/rules/context7.md

@@ -1 +1,12 @@
-# Context7 pointer: canonical policy lives in `~/.claude/system-prompts/software-engineer.xml` under `<context7>`.
+---
+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

package/rules/explore-thoroughly.md

@@ -1 +1,27 @@
-# Explore-thoroughly pointer: canonical policy lives in `~/.claude/system-prompts/software-engineer.xml` under `<investigation>`.
+# 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.

package/rules/git-workflow.md

@@ -1 +1,42 @@
-# Git-workflow pointer: canonical git workflow policy lives in `~/.claude/system-prompts/software-engineer.xml` under `<git_workflow>`.
+# 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 |

package/rules/parallel-tools.md

@@ -1 +1,23 @@
-# Parallel-tools pointer: canonical policy lives in `~/.claude/system-prompts/software-engineer.xml` under `<agent_workflow>`.
+# 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.

package/rules/research-mode.md

@@ -1 +1,23 @@
-# Research-mode pointer: canonical policy lives in `~/.claude/system-prompts/software-engineer.xml` under `<investigation>`.
+# 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.

package/rules/right-sized-engineering.md

@@ -1 +1,28 @@
-# Right-sized-engineering pointer: canonical policy lives in `~/.claude/system-prompts/software-engineer.xml` under `<scope_discipline>`.
+# 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.

package/rules/self-contained-docs.md

@@ -1 +1,17 @@
-# Self-contained-docs pointer: canonical policy lives in `~/.claude/system-prompts/software-engineer.xml` under `<documentation>`.
+# 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/tdd.md

@@ -0,0 +1,7 @@
+# TDD Process: Red-Green-Refactor
+
+**TEST-DRIVEN DEVELOPMENT IS NON-NEGOTIABLE.** Every single line of production code must be written in response to a failing test. No exceptions.
+
+1. **Red**: Write failing test. NO PRODUCTION CODE.
+2. **Green**: MINIMUM code to pass. Resist urge for more.
+3. **Refactor**: Assess improvements. Only if valuable.

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

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

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