claude-dev-env 1.38.1 → 1.40.0

package/skills/rule-creator/SKILL.md

@@ -1,150 +0,0 @@
----
-name: rule-creator
-description: "Creates or hardens Codex rules in .Codex/rules/*.md. Analyzes behavioral patterns and converts them into persistent, enforceable rule files. Triggers: 'create rule', 'add rule', 'harden rule', 'enforce rule', 'new rule'."
----
-
-# Rule Creator
-
-## Overview
-
-Creates well-structured `.Codex/rules/*.md` files that Codex loads into every session.
-
-**Core principle:** Rules encode "always true" behaviors. A rule eliminates repeated manual prompting by making the instruction persistent and automatic.
-
-**Announce at start:** "I'm using the rule-creator skill to [create/harden] a rule."
-
-**Context:** Rules are loaded at session start. They complement AGENTS.md (high-level project instructions) and skills (on-demand workflows). Use rules for behavioral constraints that must always be active.
-
-## The Process
-
-### Step 1: Understand the Need
-
-Before writing, clarify:
-
-1. **What behavior** should this rule enforce or prevent?
-2. **Why** is it needed? (What goes wrong without it? What do you manually correct?)
-3. **Scope** — all projects (`~/.Codex/rules/`) or project-specific (`.Codex/rules/`)?
-4. **Path-scoped?** — does it only apply to certain file types?
-
-### Step 2: Check for Overlap
-
-Search existing rules before creating a new one:
-
-1. Read `~/.Codex/rules/*.md` and `.Codex/rules/*.md`
-2. Read AGENTS.md for related instructions
-3. If overlap exists: **harden the existing rule** instead of creating a duplicate
-
-### Step 3: Write the Rule
-
-Follow these principles from Anthropic's prompting best practices and Codex docs:
-
-**Structure:**
-- Optional YAML frontmatter (only if path-scoped or needs `alwaysApply`)
-- Markdown with headers and bullets
-- Target under 50 lines per rule file (rules are loaded every session — token cost matters)
-
-**Writing principles (source: [Anthropic Prompting Best Practices](https://platform.Codex.com/docs/en/build-with-Codex/prompt-engineering/Codex-prompting-best-practices)):**
-
-1. **Tell what TO do, not what NOT to do.** Positive instructions outperform negative ones.
-   - Instead of: "Do not guess CSS selectors"
-   - Write: "Read the actual HTML source before writing any CSS selector"
-
-2. **Add context/motivation (WHY).** Codex generalizes from explanations.
-   - Instead of: "NEVER use ellipses"
-   - Write: "Never use ellipses because the text-to-speech engine cannot pronounce them"
-
-3. **Be specific enough to verify.** Vague rules get ignored.
-   - Instead of: "Write clean code"
-   - Write: "Use 2-space indentation, no trailing whitespace"
-
-4. **Use XML tags for critical constraints.** Wrap non-negotiable rules in semantic tags.
-   ```
-   <investigate_before_answering>
-   Read referenced files before making claims about their contents.
-   </investigate_before_answering>
-   ```
-
-5. **Dial back aggressive language for the current model.** The model overtriggers on "CRITICAL", "MUST", "ALWAYS" — use normal prompting unless enforcement truly requires it.
-
-**Frontmatter reference:**
-```yaml
-# Path-scoped rule (loads only when matching files are opened):
----
-paths:
-  - "src/api/**/*.ts"
----
-
-# Always-apply rule (loads every session, no conditions):
-# Simply omit frontmatter entirely — rules without frontmatter load unconditionally.
-
-# AVOID using alwaysApply: false — it makes the rule load-on-demand only,
-# which means it may never activate unless Codex happens to read matching files.
-```
-
-### Step 4: Choose Filename
-
-- Lowercase, hyphens only: `investigate-first.md`, `parallel-tools.md`
-- Descriptive of the behavior: name after what the rule DOES, not the problem it prevents
-- Match naming convention of existing rules in the target directory
-
-### Step 5: Validate
-
-Before writing the file:
-
-- [ ] Under 50 lines (concise enough to load every session without waste)
-- [ ] Positive instructions (tells what TO do)
-- [ ] Includes WHY context where non-obvious
-- [ ] Specific enough to verify compliance
-- [ ] No overlap with existing rules or AGENTS.md
-- [ ] No frontmatter if it should always load (omit = unconditional)
-- [ ] Path-scoped frontmatter only if genuinely file-type-specific
-
-### Step 6: Write and Confirm
-
-1. Write the rule to the target directory
-2. Show the user the final content for review
-3. Note: rules take effect on the NEXT session (Codex caches at startup)
-
-## Hardening Existing Rules
-
-When a rule exists but isn't being followed:
-
-1. **Check frontmatter** — `alwaysApply: false` prevents auto-loading. Remove it.
-2. **Check for conflicts** — contradictory rules in other files cause arbitrary behavior
-3. **Add WHY context** — unexplained rules get lower adherence
-4. **Reframe as positive** — convert "NEVER do X" to "Always do Y instead"
-5. **Add XML wrapper** — for critical rules, semantic tags improve parsing:
-   ```xml
-   <rule_name>
-   Instruction here.
-   </rule_name>
-   ```
-6. **Reduce aggressive language** — the current model overtriggers on "CRITICAL/MUST/ALWAYS". Use direct, normal language unless the rule truly requires absolute enforcement.
-
-## Red Flags — STOP
-
-- Rule duplicates something already in AGENTS.md or another rule
-- Rule is over 50 lines (split it or move details to a referenced doc)
-- Rule uses only negative instructions ("NEVER", "DON'T") without positive alternatives
-- Rule has `alwaysApply: false` for something that should always be active
-- Rule is too vague to verify ("write good code")
-
-## Rationalization Prevention
-
-| Excuse | Reality |
-|--------|---------|
-| "This is already in AGENTS.md" | If it's not being followed, it needs a dedicated rule with WHY context |
-| "The rule is short enough, no WHY needed" | WHY context improves adherence even for short rules — Codex generalizes from explanations |
-| "I'll use CRITICAL/MUST to make it stronger" | the current model overtriggers on aggressive language. Direct, calm instructions work better. |
-| "alwaysApply: false is fine, Codex will find it" | On-demand loading means the rule may never activate. Omit frontmatter for always-on rules. |
-
-## Remember
-
-- Omit frontmatter = always loads (this is what you want for most rules)
-- `alwaysApply: false` = on-demand only (use sparingly)
-- `paths:` frontmatter = loads when matching files are opened
-- Positive instructions > negative instructions
-- WHY context > bare commands
-- Under 50 lines per rule file
-- One behavior per rule file
-- Rules take effect next session

package/skills/searching-obsidian-vault/SKILL.md

@@ -1,131 +0,0 @@
----
-name: searching-obsidian-vault
-description: >-
-  Retrieves Obsidian vault context from %USERPROFILE%/SessionLog/ via the
-  configured mcp__obsidian__* server. Searches sessions/, decisions/, and
-  Research/. Use when the user says "yesterday", "last night", "the other
-  day", "earlier today", "this morning", "a few days ago", "last week",
-  "this past week", "a while back", "recently", "recent session", "last
-  session", or "previous session"; when the user asks why existing code
-  was built a certain way or whether an approach was tried before; when
-  starting a session in a git repo whose name matches a project folder
-  under sessions/; or when the user names a specific component, decision,
-  gotcha, or prior research note.
----
-
-# Obsidian Vault
-
-## Overview
-
-Invoke this skill when prior session history, decisions, or research from
-the Obsidian vault would change how the current task is executed. Load it
-on demand rather than keeping the full vault policy always-on.
-
-The retrieval *mechanics* live in `/recall`. The
-`vault_context_retrieved` frontmatter bookkeeping lives in `/session-log`
-Step 2. This skill's job is to make the vault search happen at the right
-moments so the downstream flag can be set honestly.
-
-## Trigger Conditions
-
-Invoke automatically when any of the following holds:
-
-- The user says "yesterday", "last night", "the other day", "earlier
-  today", "this morning", "a few days ago", "last week", "this past
-  week", "a while back", "recently", "recent session", "last session",
-  or "previous session".
-- The user asks why existing code was built a certain way, or whether an
-  approach was tried before.
-- A new session starts in a git repo whose name matches a project folder
-  under `sessions/`.
-- The user names a specific component, feature, or architectural decision
-  that a session or decision note might exist for.
-- The user mentions "session", "decision", "gotcha", "superseded", or
-  "prior research" by name.
-
-Skip the skill for isolated lookups with no project history (e.g. one-off
-utility scripts, pure syntax questions, fresh repos with no
-`sessions/[project]/` folder).
-
-## Search Algorithm
-
-1. **Search by frontmatter first.** Call `mcp__obsidian__search_notes` with
-   `searchFrontmatter: true` and the project name (inferred from the git
-   remote, working directory, or topic under discussion). Then search by
-   content keywords such as `blocked`, `superseded`, `decision`, `gotcha`,
-   plus task-specific terms (component names, error messages, library names).
-
-   Concrete example:
-
-   ```xml
-   <invoke name="mcp__obsidian__search_notes">
-     <parameter name="query">claude-code-config</parameter>
-     <parameter name="searchFrontmatter">true</parameter>
-   </invoke>
-
-   <invoke name="mcp__obsidian__search_notes">
-     <parameter name="query">superseded decision themes-pr-stack</parameter>
-   </invoke>
-   ```
-
-2. **Scope to the three vault folders.**
-   - `sessions/` — session reports (`type: session-report`, `project`,
-     `session`, `date`, `status`, `blocked`, `tags`).
-   - `decisions/` — decision notes (`type: decision|procedural|fact|gotcha`,
-     `project`, `date`, `status: Active|Superseded`, `tags`).
-   - `Research/` — deep research documents.
-
-3. **Read the top 3–5 hits.** Use `mcp__obsidian__read_note` for single notes
-   or `mcp__obsidian__read_multiple_notes` for several at once. Prefer recent
-   notes over older ones, and prefer decision notes and session summaries
-   over raw research.
-
-4. **Summarise the relevant prior context** inline before proceeding with
-   the work, so the user can see what prior history shaped the current
-   approach. Call out any decision marked `status: Superseded`.
-
-5. **Record the outcome for `/session-log`.** Set
-   `vault_context_retrieved: true` if any `mcp__obsidian__*` read or search
-   tool was used productively (at least one relevant note surfaced and
-   informed the work). Set it to `false` if the vault was unreachable or no
-   relevant notes were found.
-
-## Session-End Integration
-
-At the end of substantive sessions, offer to run `/session-log`. Step 2 of
-`/session-log` already auto-detects vault MCP calls and writes the
-`vault_context_retrieved` field into frontmatter. This skill's contribution
-is to ensure those MCP calls actually happen when they should, so the flag
-ends up `true` whenever genuine prior context exists.
-
-## Frontmatter Requirement
-
-Any session note written via `/session-log` after invoking this skill must
-include:
-
-```yaml
-vault_context_retrieved: true   # or false
-```
-
-`true` means a `mcp__obsidian__*` read or search tool was used productively
-during the session. `false` means the vault was unreachable or no relevant
-notes existed.
-
-## Vault Location
-
-The vault lives at `%USERPROFILE%/SessionLog/` on this workspace
-(expanding to the user's Windows profile directory). It is accessed
-entirely through the `mcp__obsidian__*` MCP server, whose own
-configuration holds the concrete path; `OBSIDIAN_VAULT_PATH` serves the
-same role on systems that resolve the vault outside the MCP server. This
-skill does not read the filesystem directly and must not hard-code a
-user-specific path like `C:/Users/<name>/SessionLog/` in code it
-produces — expand `%USERPROFILE%` (or read `OBSIDIAN_VAULT_PATH`) at run
-time.
-
-## Related Skills
-
-- `/recall` performs the retrieval mechanics end-to-end with user-facing
-  output.
-- `/session-log` consumes the `vault_context_retrieved` flag this skill is
-  responsible for keeping honest.

package/skills/skill-writer/REFERENCE.md

@@ -1,284 +0,0 @@
-# Skill writer -- reference
-
-## Canonical resources
-
-When authoring or refining skills, ground decisions in these sources. If guidance conflicts, defer to the higher tier.
-
-### Tier 1: Anthropic (primary authority for Claude)
-
-- https://platform.claude.com/docs/en/claude-code/skills -- official skill structure, frontmatter fields, progressive disclosure, string substitutions, directory layout.
-- https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices -- the single living reference for Claude's latest models. Covers XML tags, tool use, thinking, agentic systems, overeagerness, anti-hallucination.
-- https://transformer-circuits.pub/2026/emotions/index.html -- emotion concepts research (April 2026): 171 internal activation patterns that causally influence behavior. Key skill-writing takeaways: clear criteria and escape routes improve output quality, collaborative framing activates engagement, positive task framing correlates with better results.
-- https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking -- adaptive thinking reference; replaces manual budget_tokens with effort-based control.
-
-### Tier 2: Major labs (strong secondary, often transfers across models)
-
-- https://platform.openai.com/docs/guides/prompt-engineering -- six strategies: clear instructions, reference text, split complex tasks, give models time to think, use external tools, test systematically.
-- https://deepmind.google/research/ -- chain-of-thought and structured reasoning research.
-
-### Tier 3: Community and individuals (supplementary)
-
-- https://simonwillison.net/ -- practical LLM experiments, skill patterns, and automation insights.
-- https://www.deeplearning.ai/short-courses/ -- foundational prompt engineering courses.
-- https://www.latent.space/ -- AI engineering perspective.
-
-### Conflict resolution rule
-
-If sources disagree on a technique, apply in order: Anthropic documentation first (it describes the actual model behavior), then OpenAI/Google/Microsoft (large-scale research with cross-model relevance), then community sources (patterns and intuition, not authoritative on model internals). When Tier 3 contradicts Tier 1, Tier 1 wins without exception.
-
----
-
-## Complete frontmatter fields
-
-Source: [Claude Code Skills](https://platform.claude.com/docs/en/claude-code/skills)
-
-### Required fields
-
-| Field | Type | Constraints | Description |
-|-------|------|-------------|-------------|
-| `name` | string | Lowercase, hyphens, numbers. Max 64 chars. No `anthropic` or `claude`. | Must match directory name. Prefer gerund form. |
-| `description` | string | Max 1024 chars. Third person. No XML tags. | What it does + when to use it + trigger phrases. |
-
-### Optional fields
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `allowed-tools` | string | (all tools) | Tools permitted without asking. E.g., `Read, Grep, Bash(python *)` |
-| `context` | string | (inline) | Set to `fork` to run in isolated subagent (no conversation history) |
-| `agent` | string | (default) | Subagent type when `context: fork` is set |
-| `model` | string | (inherits) | Model override when skill is active |
-| `effort` | string | (inherits) | `low`, `medium`, `high`, or `max` (Opus only) |
-| `user-invocable` | boolean | `true` | Set `false` to hide from `/` menu (background knowledge only) |
-| `disable-model-invocation` | boolean | `false` | Set `true` for manual-only via `/name` |
-| `paths` | string/list | (all files) | Glob patterns limiting activation. E.g., `"*.py"` or `["*.ts", "*.tsx"]` |
-| `argument-hint` | string | (none) | Autocomplete hint. E.g., `[filename] [format]` |
-| `shell` | string | `bash` | Shell for `` !`command` `` blocks. `bash` or `powershell` |
-| `hooks` | object | (none) | Hooks scoped to this skill's lifecycle |
-
-### String substitutions (available in SKILL.md body)
-
-| Variable | Description |
-|----------|-------------|
-| `$ARGUMENTS` | All arguments passed when invoking |
-| `$ARGUMENTS[N]` | Specific argument by 0-based index |
-| `$N` | Shorthand for `$ARGUMENTS[N]` (e.g., `$0`, `$1`) |
-| `${CLAUDE_SESSION_ID}` | Current session ID |
-| `${CLAUDE_SKILL_DIR}` | Directory containing SKILL.md |
-| `` !`command` `` | Dynamic context injection -- shell command runs before Claude sees content |
-
-### Permission syntax
-
-```
-Skill(name)        # Allow exact skill
-Skill(name *)      # Allow skill with any arguments
-```
-
----
-
-## Progressive disclosure architecture
-
-Source: [Claude Code Skills](https://platform.claude.com/docs/en/claude-code/skills)
-
-Skills load in three levels to minimize context usage:
-
-| Level | What loads | Token cost | When |
-|-------|-----------|------------|------|
-| **1. Metadata** | `name` and `description` from frontmatter | ~100 tokens | Always (system prompt) |
-| **2. Instructions** | SKILL.md body | <5k tokens | When triggered by matching request |
-| **3. Resources** | Additional files, scripts, schemas | Unlimited | When referenced from instructions |
-
-### Implications for skill authors
-
-- Many skills can coexist with minimal context cost (~100 tokens each at Level 1)
-- SKILL.md body should stay under 500 lines to fit the <5k token budget
-- Scripts execute via bash -- their code never enters context, only output does
-- Reference files load only when Claude reads them via `@` reference or explicit Read
-- Heavy lookup tables, field mappings, and long examples belong in REFERENCE.md or separate files
-
----
-
-## Content templates by degree of freedom
-
-### High freedom (advisory)
-
-For guidance where multiple approaches are valid. States goals and acceptance criteria without prescribing exact steps.
-
-```markdown
----
-name: analyzing-data
-description: >-
-  Analyzes datasets and generates statistical summaries. Use when working
-  with CSV or Excel data requiring descriptive statistics, correlations,
-  or visualizations. Triggers: 'analyze data', 'statistical summary'.
----
-
-# Analyzing data
-
-**Core principle:** Let the data structure guide the analysis approach.
-
-## When this skill applies
-
-Trigger when the user has tabular data and wants statistical insight,
-trend identification, or visualization.
-
-## Goals
-
-1. Inspect the data structure and report shape, types, missing values
-2. Generate descriptive statistics appropriate to the data types
-3. Identify correlations and patterns worth highlighting
-4. Produce visualizations if requested
-
-## Output format
-
-Summary with key findings first, then supporting tables and charts.
-Explain statistical choices so the user can evaluate appropriateness.
-
-## Examples
-
-**Input:** "Analyze sales_2024.csv for trends"
-**Output:** Monthly trend summary, top performers, seasonal patterns,
-with charts for the clearest visual signals.
-```
-
-### Medium freedom (structured workflow)
-
-For preferred patterns with room for adaptation. States a recommended sequence but allows deviation when justified.
-
-```markdown
----
-name: reviewing-plans
-description: >-
-  Validates implementation plans against code standards and TDD compliance.
-  Use after writing plans and before executing them.
-  Triggers: 'review plan', 'validate plan', 'check plan'.
----
-
-# Reviewing plans
-
-**Core principle:** Bad plans produce bad code. Validate before executing.
-
-## When this skill applies
-
-Use after a plan has been written and before execution begins.
-This is the quality gate between planning and implementation.
-
-## The process
-
-### Step 1: Locate plan files
-Find plan files in `.planning/phases/` or `docs/plans/`.
-
-### Step 2: Review dimensions
-Check each dimension: structure completeness, TDD compliance,
-code quality standards, right-sized engineering, task granularity.
-
-### Step 3: Report verdict
-Deliver READY or NEEDS REVISION with specific issues and locations.
-
-## Output format
-
-| Dimension | Status | Notes |
-|-----------|--------|-------|
-| Structure | PASS/FAIL | [specific finding] |
-| TDD | PASS/FAIL | [specific finding] |
-| Code quality | PASS/FAIL | [specific finding] |
-```
-
-### Low freedom (exact sequence)
-
-For fragile operations where deviation causes silent failures. States precisely what to do, in what order, with validation at each step.
-
-```markdown
----
-name: filling-pdf-forms
-description: >-
-  Fills PDF forms using pdf-lib with exact field mapping and validation.
-  Use when populating PDF forms programmatically.
-  Triggers: 'fill PDF form', 'populate form', 'form filling'.
-allowed-tools: Bash(node *), Read
----
-
-# Filling PDF forms
-
-**Core principle:** Extract field names first, then map, then fill.
-Guessing field names produces silently empty forms.
-
-## Before filling any form
-
-1. Read `${CLAUDE_SKILL_DIR}/FORMS.md` for the field mapping reference
-2. Extract field names: `node ${CLAUDE_SKILL_DIR}/scripts/extract_fields.js input.pdf`
-3. Match extracted fields against the mapping before writing any fill code
-
-## Workflow
-
-### Step 1: Extract fields
-```bash
-node ${CLAUDE_SKILL_DIR}/scripts/extract_fields.js "$0"
-```
-
-### Step 2: Generate fill script
-Use the field mapping from FORMS.md. Set every field explicitly.
-
-### Step 3: Execute and validate
-```bash
-node fill_script.js && node ${CLAUDE_SKILL_DIR}/scripts/validate_fill.js output.pdf
-```
-
-### If validation fails
-Read error output, fix the field mapping, re-execute, re-validate.
-Do not proceed with a partially filled form.
-```
-
----
-
-## Validation checklist
-
-Source: [Claude Code Skills](https://platform.claude.com/docs/en/claude-code/skills)
-
-### Structure
-- [ ] SKILL.md in correct location (matches `name` directory)
-- [ ] Valid YAML frontmatter with required fields
-- [ ] Body under 500 lines
-- [ ] Heavy content in separate reference files
-
-### Description quality
-- [ ] Third person ("Analyzes..." not "Analyze...")
-- [ ] Includes what it does and when to use it
-- [ ] Contains trigger phrases matching natural user language
-- [ ] Under 1024 characters
-- [ ] No XML tags in description
-
-### Content quality
-- [ ] Core principle stated (one sentence)
-- [ ] Steps are sequential and numbered
-- [ ] States desired behavior in positive terms
-- [ ] Motivation provided for constraints (why, not just what)
-- [ ] Examples are concrete with specific inputs and outputs
-- [ ] No time-sensitive claims (or clearly dated)
-- [ ] Consistent terminology throughout
-- [ ] File references are one level deep from SKILL.md
-- [ ] Files over 100 lines have a table of contents
-
-### Technical correctness
-- [ ] `allowed-tools` specified if skill needs specific tools
-- [ ] `argument-hint` included if skill accepts arguments
-- [ ] `paths` set if skill applies only to certain file types
-- [ ] String substitutions use correct syntax
-- [ ] Script references use `${CLAUDE_SKILL_DIR}` for portability
-- [ ] MCP tools use fully qualified names (`ServerName:tool_name`)
-
-### Testing readiness
-- [ ] At least 3 evaluation scenarios identified
-- [ ] Covers a typical case, an edge case, and a decline/clarify case
-- [ ] Golden rule: a colleague could follow this skill without extra context
-
----
-
-## Evaluation loop
-
-For skill drafts that need iteration:
-
-1. Trigger the skill with 2-3 representative user requests.
-2. Note failure modes (missed triggers, wrong output format, overstepped scope).
-3. Tighten trigger phrases, add examples, or adjust degree of freedom for the failure class only.
-
-Anthropic's **self-correction chaining** pattern extends this: generate a draft, have Claude review it against the validation checklist, then refine based on the review.