claude-dev-env 1.19.2 → 1.20.1

package/CLAUDE.md

@@ -0,0 +1,16 @@
+# Claude Development Assistant
+
+Canonical behavior policy lives in `~/.claude/system-prompts/software-engineer.xml`.
+
+## Canonical Pointers
+
+- 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
+
+## Additional Non-overlapping Rules
+
+- 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`

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/docs/CODE_RULES.md

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

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.2",
+    "version": "1.20.1",
     "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/agent-spawn-protocol.md

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

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/cleanup-temp-files.md

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

package/rules/code-reviews.md

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