claude-dev-env 1.0.0

package/rules/git-workflow.md

@@ -0,0 +1,42 @@
+# 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

@@ -0,0 +1,23 @@
+# 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

@@ -0,0 +1,23 @@
+# 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

@@ -0,0 +1,28 @@
+# 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/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

@@ -0,0 +1,12 @@
+# Testing Standards
+
+> **Reference:** TEST_QUALITY.md - Load when writing or reviewing tests.
+
+@${CLAUDE_PLUGIN_ROOT}/docs/TEST_QUALITY.md
+
+## Complete Mocks for Testability
+
+**Mocks must include all fields the component actually uses.**
+
+If a component renders field X, the mock must have field X with a valid value.
+Incomplete mocks make it impossible to distinguish "broken code" from "missing data".

package/skills/agent-prompt/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: agent-prompt
+description: >-
+  Craft a structured prompt using prompt-generator's workflow, then spawn a
+  background agent to execute it after user approval. Use instead of
+  /prompt-generator when the user wants execution, not just the prompt.
+  Triggers on /agent-prompt, "launch an agent for this", "spawn agent to do X",
+  "delegate this", "run this in background", or any task that benefits from
+  agent delegation with prompt quality.
+---
+
+@~/.claude/skills/prompt-generator/SKILL.md
+@~/.claude/skills/prompt-generator/REFERENCE.md
+
+# Agent Prompt
+
+Craft a structured agent prompt, get approval, spawn a background agent.
+
+The prompt-generator skill above defines the prompt-crafting workflow. This skill extends it: instead of delivering the prompt as a fenced block, it presents the prompt for approval and spawns a background agent.
+
+## When this skill applies
+
+Trigger when the user wants to delegate a task to an agent. The difference from /prompt-generator: this skill **executes**.
+
+When invoked with arguments (e.g. `/agent-prompt fix the auth bug via TDD`), treat the arguments as the task to build a prompt for and execute.
+
+## Workflow
+
+### Steps 1-8: Craft the prompt
+
+Follow the prompt-generator workflow steps 1 through 8 exactly as written. Classify the prompt type, set degree of freedom, collect missing facts, build the prompt with XML tags and role, control format and style, add examples if needed, and self-check against the rubric.
+
+Skip step 9 (Deliver). Continue below instead.
+
+### Step 9: Gather context before crafting
+
+The agent starts with zero conversation history. Before building the prompt, use Read, Glob, Grep, and other research tools to gather the concrete values the agent will need -- file paths, function signatures, existing patterns, branch names. Embed these directly in the prompt instead of telling the agent to "find" them.
+
+The agent-spawn-protocol rule requires this: if any context question has the answer "I don't know", investigate first. Do not delegate the context-gathering.
+
+Proactive context gathering enables agents to plan effectively from the start. Anthropic's emotion concepts research (2026) found that agents produce higher-quality output when they understand constraints, available tools, and system boundaries upfront — they incorporate these into their approach naturally, leading to better first attempts and more accurate results.
+
+### Step 10: Determine agent configuration
+
+Map the task to agent parameters:
+
+| Task type | subagent_type | mode |
+|---|---|---|
+| Codebase exploration, search, research | Explore | default |
+| Code implementation, bug fix, refactoring | general-purpose | auto |
+| Read-only audit, analysis, review | general-purpose | default |
+| Architecture, multi-step planning | Plan | plan |
+
+Always set `run_in_background: true`.
+
+Generate a descriptive `name` (3-5 words, kebab-case) so the user can track progress and send follow-up messages via `SendMessage({to: name})`.
+
+### Step 11: Present for approval
+
+Use AskUserQuestion with one question. The question text should summarize the agent config (type, mode, name). Each option should use the `preview` field to show the full crafted prompt.
+
+Options:
+1. "Launch it" (recommended) -- preview shows the crafted prompt
+2. "Edit first" -- preview shows the prompt with a note that user can provide changes
+3. "Cancel" -- no preview
+
+### Step 12: Spawn
+
+On **"Launch it"**: spawn the Agent tool with the crafted prompt and configuration. Report the agent name so the user knows what's running.
+
+On **"Edit first"**: present the prompt in conversation text. After the user provides changes, return to step 11 with the updated prompt.
+
+On **"Cancel"**: acknowledge and stop.
+
+## Prompt adjustments for agent execution
+
+When building the prompt in step 4, these adjustments ensure the agent can work independently:
+
+**Context completeness** -- include file paths, line numbers, function names, branch state, and anything you learned during step 9. The agent cannot see this conversation.
+
+**Acceptance criteria** -- state what "done" looks like. For code: include the test command. For research: specify the output format and save location.
+
+**Scope boundary** -- include "Only make changes directly requested; do not refactor surrounding code" or equivalent. Agents without scope constraints tend to over-engineer.
+
+**Constraints from this project** -- if the project has CODE_RULES.md, TDD requirements, or naming conventions, include the relevant subset in the prompt so the agent follows them.
+
+**Emotion-informed briefing** -- Anthropic's emotion concepts research (2026) found that briefing style causally affects output quality. Frame tasks collaboratively ("work on this together", "help figure out"). Include permission to express uncertainty ("flag anything you're unsure about", "use [PLACEHOLDER] for unverified specifics"). Provide motivation behind constraints ("this ordering ensures tests define behavior before implementation exists"). Share system context proactively (what hooks enforce, what tools are available, what the fallback is) so the agent can incorporate constraints into its plan from the start.
+
+**Anti-test-fixation** -- For code tasks, include guidance against test-specific solutions. Anthropic: "Implement a solution that works correctly for all valid inputs, not just the test cases. Tests are there to verify correctness, not to define the solution. If the task is unreasonable or infeasible, or if any of the tests are incorrect, please inform me rather than working around them."
+
+**Commit-and-execute** -- For multi-step agent work, include decision commitment guidance. Anthropic: "When deciding how to approach a problem, choose an approach and commit to it. Avoid revisiting decisions unless you encounter new information that directly contradicts your reasoning."
+
+**Temp file cleanup** -- If the agent may create scratch files during iteration, include cleanup instructions. Anthropic: "If you create any temporary new files, scripts, or helper files for iteration, clean up these files by removing them at the end of the task."
+
+## Constraints
+
+- Always present for approval via AskUserQuestion -- never auto-spawn
+- Always run agents in background
+- Gather context before crafting -- do not send an agent in blind
+- If the task is too small for an agent (single file read, quick grep), say so and just do it directly
+- Include obstacle handling: "When encountering obstacles, do not use destructive actions as a shortcut (e.g. --no-verify, discarding unfamiliar files)" -- agents without this guidance may take irreversible shortcuts
+- Frame agent tasks with collaborative language and include permission to express uncertainty — agents produce higher-quality output with collaborative briefing (Anthropic emotion concepts research, 2026)

package/skills/anthropic-plan/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: anthropic-plan
+description: Structured implementation planning through readonly codebase exploration before any code changes. Produces a plan file for approval. Use when the user says /anthropic-plan, "plan this first", "think before coding", "explore before implementing", "make a plan", or when approaching non-trivial tasks that benefit from upfront exploration and design. Also triggers on "what would the approach be", "scope this out", or "don't code yet, just plan".
+---
+
+# Claude Plan
+
+Explore the codebase, design an approach, and write a plan file -- all without touching production code.
+
+## Why
+
+Jumping straight to code on non-trivial tasks leads to wasted effort when the approach conflicts with existing patterns, misses reusable code, or misunderstands the user's intent. This skill enforces "look before you leap": explore first, design second, write the plan third, get approval last. No code changes until the user says go.
+
+## Constraints
+
+Treat the codebase as readonly throughout this skill. The only file you may create or edit is the plan file.
+
+**Allowed:** Read files, Grep, Glob, launch Explore agents, launch Plan agents, write/edit the plan file, AskUserQuestion for clarification.
+
+**Not allowed:** Edit source files, Write new source files, run tests, install packages, run non-readonly Bash commands, or make any system changes.
+
+This discipline exists because the user invoked this skill specifically to understand the approach before committing to it. Violating readonly would undermine the whole point.
+
+## Plan File
+
+Write to `~/.claude/plans/<slug>.md`.
+
+Generate the slug from the task -- descriptive, kebab-case, 2-4 words. Examples: `add-user-auth.md`, `fix-payment-retry.md`, `refactor-config-loading.md`. Avoid the random-word convention used by built-in plan mode.
+
+**Announce at start:** "Planning: `<slug>` -- exploring before writing code."
+
+## Workflow
+
+### Phase 1: Explore
+
+Understand the problem space before proposing solutions. Launch Explore agents in parallel -- up to 3, but use the minimum needed. Quality over quantity.
+
+What to look for:
+- Files and modules the task will touch
+- Existing patterns for similar functionality
+- Utilities, helpers, constants, and shared code to reuse
+- Test patterns already in place
+
+Skip this phase only if the task is trivial and full context already exists in the conversation.
+
+### Phase 2: Design
+
+Launch Plan agent(s) to design the implementation -- up to 3 for complex or multi-area tasks, skip entirely for trivial tasks. Feed them comprehensive context from Phase 1; they cannot explore on their own, so everything they need must come from you.
+
+### Phase 3: Review
+
+Before committing to the plan:
+- Read the critical files yourself to verify the agents got it right
+- Check alignment with what the user actually asked for
+- If requirements are ambiguous, use AskUserQuestion now -- not after writing the plan
+
+### Phase 4: Write the Plan
+
+Write incrementally as you learn things in Phases 1-3, then refine here. The plan file has these sections:
+
+```markdown
+## Context
+Why this change is needed, what problem it solves, what the outcome looks like.
+
+## Approach
+The recommended implementation. One approach, not a menu of alternatives.
+Concise but detailed enough to execute without re-exploring.
+
+## Files
+Critical file paths that will be created or modified.
+
+## Reuse
+Existing functions, utilities, constants, or patterns to leverage.
+Include file:line references so the implementer can find them instantly.
+
+## Steps
+Ordered implementation steps. Each step is a discrete, testable unit of work.
+
+## Verification
+How to confirm end-to-end that the implementation works.
+Specific commands, test files, or manual verification steps.
+
+## Bash Permissions
+Semantic descriptions of bash actions the implementation will need:
+- "run tests"
+- "install dependencies"
+- "start dev server"
+These are action descriptions, not specific commands.
+```
+
+### Phase 5: Present for Approval
+
+Use AskUserQuestion to present the completed plan. Do not ask about approval in regular text -- always use AskUserQuestion so the user gets a clear, structured decision point.
+
+Options:
+- **Approve** -- proceed with implementation
+- **Revise** -- user has feedback to incorporate
+- **Cancel** -- abandon the plan
+
+## Scaling
+
+Not every task needs all five phases. Match effort to complexity:
+
+- **Trivial** (rename, typo fix): Ask if a formal plan is even wanted. If yes, skip Phases 1-2, write a minimal plan.
+- **Small** (single-file change, clear scope): One Explore agent, skip Design phase, concise plan.
+- **Medium** (multi-file feature, some ambiguity): Full workflow, 1-2 agents per phase.
+- **Large** (cross-cutting change, architectural): Full workflow, max agents, thorough Review phase.

package/skills/everything-search/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: everything-search
+description: Fast file search on Windows using Everything (voidtools) es.exe command-line tool. Use when searching for files by extension, name, date modified, size, or path. Triggers on "find files", "search for files", "locate files", or when user asks to use Everything.
+---
+
+# Everything Search
+
+## Overview
+
+Search files instantly on Windows using the Everything command-line interface (es.exe).
+
+**Announce at start:** "I'm using the everything-search skill to find files."
+
+## Instructions
+
+### Command Syntax
+
+**Path (WSL):** `/mnt/c/Program\ Files/Everything/es.exe`
+**Path (Windows):** `"C:/Program Files/Everything/es.exe"`
+
+**CRITICAL:**
+- Search terms are SPACE-SEPARATED, not quoted together
+- When searching a path, use backslashes inside quotes: `"Y:\\path\\to\\folder"`
+
+```bash
+# CORRECT - WSL format with path search
+/mnt/c/Program\ Files/Everything/es.exe "Y:\\path\\to\\folder" searchterm
+
+# CORRECT - space-separated terms
+/mnt/c/Program\ Files/Everything/es.exe ext:mp4 dm:last3months
+
+# WRONG - quoted with semicolons (breaks parsing)
+/mnt/c/Program\ Files/Everything/es.exe "ext:mp4;mov;avi dm:last3months"
+```
+
+### Search Operators
+
+**By Extension:**
+```bash
+ext:mp4                    # Single extension
+ext:mp4 | ext:mov | ext:avi  # Multiple extensions (OR)
+```
+
+**By Date Modified:**
+```bash
+dm:last3months            # Modified in last 3 months
+dm:lastweek               # Modified in last week
+dm:today                  # Modified today
+dm:>=2024-01-01           # Modified on or after date
+```
+
+**By Path:**
+```bash
+/mnt/c/Program\ Files/Everything/es.exe "D:\\Projects\\My App\\assets" ext:mp4
+/mnt/c/Program\ Files/Everything/es.exe "D:\\Projects" ext:prproj
+```
+
+**By Size:**
+```bash
+size:>100mb               # Larger than 100MB
+size:<1gb                 # Smaller than 1GB
+```
+
+**By Name:**
+```bash
+*.prproj                  # Wildcard match
+"exact filename.txt"      # Exact match (quote the filename)
+```
+
+### Combining Multiple Extensions
+
+Run separate searches for each extension type:
+```bash
+/mnt/c/Program\ Files/Everything/es.exe ext:mp4 dm:last3months
+/mnt/c/Program\ Files/Everything/es.exe ext:mov dm:last3months
+/mnt/c/Program\ Files/Everything/es.exe ext:prproj dm:last3months
+```
+
+### Output Options
+
+```bash
+# Sort by date modified (descending)
+/mnt/c/Program\ Files/Everything/es.exe ext:mp4 dm:last3months -sort dm -sort-descending
+
+# Limit results
+/mnt/c/Program\ Files/Everything/es.exe ext:mp4 -n 50
+
+# Show size
+/mnt/c/Program\ Files/Everything/es.exe ext:mp4 -size
+```
+
+## Examples
+
+### Video files (last 90 days)
+```bash
+/mnt/c/Program\ Files/Everything/es.exe ext:mp4 dm:last3months
+/mnt/c/Program\ Files/Everything/es.exe ext:mov dm:last3months
+/mnt/c/Program\ Files/Everything/es.exe ext:avi dm:last3months
+/mnt/c/Program\ Files/Everything/es.exe ext:mkv dm:last3months
+```
+
+### Premiere projects
+```bash
+/mnt/c/Program\ Files/Everything/es.exe ext:prproj
+/mnt/c/Program\ Files/Everything/es.exe ext:prproj dm:lastmonth
+```
+
+### Large files
+```bash
+/mnt/c/Program\ Files/Everything/es.exe size:>1gb
+/mnt/c/Program\ Files/Everything/es.exe ext:mp4 size:>500mb
+```
+
+### Config files in a project
+```bash
+/mnt/c/Program\ Files/Everything/es.exe "Y:\\path\\to\\project" config.py
+/mnt/c/Program\ Files/Everything/es.exe "Y:\\path\\to\\project" constants.py
+```
+
+## Best Practices
+
+- Everything must be running (system tray) for es.exe to work
+- Run one extension per search for cleaner results
+- Use `dm:` for recent file searches instead of manual date filtering
+- Combine with path to narrow scope
+- Results return instantly regardless of drive size
+
+### Junctions, Symlinks & Drive Mapping
+
+Everything indexes REAL paths only, not junctions or mapped drives.
+
+| Drive | Type | Indexed? | Action |
+|-------|------|----------|--------|
+| Y:\ | Real NTFS | Yes | Use this path |
+| Z:\ | Junction to Y: | No | Use Y:\ instead |
+
+**If search returns empty:**
+1. Check if the path is a junction/symlink
+2. Find the real path and search that instead
+3. Or use Glob tool as fallback (works on any path)
+
+**Common drive mappings:**
+- `Z:\Projects\` -> `Y:\Work\Projects\`
+- When in Z:\, translate to Y:\ equivalent for Everything searches

package/skills/ingest/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: ingest
+description: Digest the codebase using gitingest into LLM-friendly text files, one per top-level folder. Use when user wants to create a text digest/summary of their repo for AI consumption.
+user_invocable: true
+---
+
+# Ingest Codebase with GitIngest
+
+## Steps
+
+1. **Ensure gitingest is installed**: `pip install gitingest`
+
+2. **Clone repo locally** (avoids network drive slowness and enables long paths):
+   ```bash
+   REMOTE=$(git remote get-url origin)
+   TEMP_DIR=$(mktemp -d)/gitingest_repo
+   git clone --depth 1 -c core.longpaths=true "$REMOTE" "$TEMP_DIR"
+   ```
+
+3. **Identify top-level folders** in the clone to ingest (skip `.git`, `.Codex`, `.planning`, etc.)
+
+4. **Run gitingest Python API on each folder separately** (running separately avoids spaces-in-names breaking CLI glob patterns):
+   ```python
+   from gitingest import ingest
+
+   summary, tree, content = ingest(
+       folder_path,
+       include_patterns=["*.py", "*.md", "*.json", "*.yaml", "*.yml", "*.cfg", "*.toml", "*.txt"],
+       exclude_patterns=["**/venv/**", "**/logs/**", "**/__pycache__/**", "**/Archive/**",
+                         "**/*.png", "**/*.jpg", "**/*.mp4", "**/*.gif", "**/*.pyc",
+                         "**/*.rdp", "**/node_modules/**", "**/.git/**"],
+       max_file_size=102400,
+   )
+   ```
+
+5. **Save each digest** as `digest_<folder_name>.txt` in the corresponding source folder on the original working directory (not the temp clone)
+
+6. **Clean up** the temp clone directory
+
+7. **Report** file count, token count, and output paths for each folder