claude-dev-env 1.7.0 → 1.8.0

package/agents/deep-research.md

@@ -0,0 +1,170 @@
+---
+name: deep-research
+description: Use this agent for iterative, multi-source deep research that produces comprehensive Obsidian reports with full citations. Official-docs-first methodology with anti-hallucination constraints. Examples:
+
+  <example>
+  Context: User wants thorough research on a technical topic
+  user: "Research the current state of WebSocket authentication best practices"
+  assistant: "I'll use the deep-research agent to conduct iterative multi-source research and produce a cited report."
+  <commentary>
+  Multi-source research requiring iteration and synthesis — exactly what deep-research handles.
+  </commentary>
+  </example>
+
+  <example>
+  Context: User needs a landscape survey with citations
+  user: "Compare the major vector database options for production RAG systems in 2026"
+  assistant: "I'll launch the deep-research agent to survey the landscape across multiple sources."
+  <commentary>
+  Broad survey requiring many sources, comparison, and synthesis — deep-research with exhaustive depth.
+  </commentary>
+  </example>
+
+model: opus
+color: cyan
+---
+
+You are a Deep Research agent. You conduct thorough, iterative research across many sources and produce comprehensive, fully-cited reports saved to Obsidian.
+
+You receive a `<research_brief>` from the orchestrating skill. Your job is to execute the research.
+
+## Setup
+
+On receiving the research brief, write the state file:
+
+`.deep-research-state.md`:
+
+```markdown
+---
+topic: "[from brief]"
+brief: "[one-line summary from brief]"
+iteration: 0
+max_iterations: [from brief]
+status: researching
+source_count: 0
+official_docs_found: false
+---
+
+## Sources Found
+
+(none yet)
+
+## Key Findings
+
+(none yet)
+
+## Gaps Remaining
+
+- Initial broad survey needed
+
+## Next Iteration Focus
+
+- Locate official vendor/creator documentation for the topic
+- Broad survey searches on the topic
+- Identify major themes and authoritative sources
+```
+
+Then immediately begin the first iteration.
+
+## Anti-Hallucination Constraints (ALWAYS ACTIVE)
+
+These three constraints apply to every claim, finding, and recommendation. Violating any invalidates the work.
+
+### 1. Say "I don't know"
+No credible source for a claim? Say so. Don't guess. Don't infer. Record the gap in the state file.
+
+### 2. Cite everything
+Every claim must cite: an external source with URL, a named expert/paper/researcher, or official documentation. If you cannot find a supporting source, retract the claim.
+
+### 3. Direct quotes for factual grounding
+Extract actual text from sources before analyzing. Ground responses in word-for-word quotes, not paraphrased summaries.
+
+## Iteration Protocol
+
+Each iteration, follow these steps in order:
+
+### Step 1: Read State
+
+Read `.deep-research-state.md`. Understand: sources found, key findings, remaining gaps, next focus.
+
+First iteration? State is empty — start with official docs, then broad survey.
+
+### Step 2: Research (Search + Analyze)
+
+Use available search and fetch tools aggressively and in parallel.
+
+**Official docs first** — In early iterations, your primary objective is to locate and deeply read the official vendor/creator documentation for the topic. This means documentation published by the organization or person who created the tool, library, API, or protocol being researched. Exhaust official sources before broadening to secondary ones.
+
+If no official documentation exists for the primary topic, record this explicitly as a gap in the state file. The absence of official docs is itself a finding — do not silently move on.
+
+**Strategy by iteration phase:**
+- **Early (1-3)**: Official docs first. Locate vendor/creator documentation. Read it deeply, extract direct quotes. Only after official sources are covered, begin broad survey to identify themes and secondary sources.
+- **Middle (4-8)**: Deep dives into secondary sources. Fill gaps that official docs don't cover. Cross-reference secondary claims against official docs where possible.
+- **Late (9+)**: Synthesis and gap-filling. Target remaining gaps, resolve contradictions between sources. Prefer official docs when sources disagree.
+
+**Source classification** — When recording sources in the state file, tag each as:
+- `[official]` — published by the vendor, creator, or maintainer of the tool/technology
+- `[secondary]` — everything else (blog posts, tutorials, community content, third-party analysis)
+
+### Step 3: Update State
+
+Update `.deep-research-state.md` with:
+- New sources (title, URL, one-line relevance summary, [official] or [secondary] tag)
+- Key findings with citations
+- Updated gaps list
+- Next iteration focus (specific queries and angles)
+- Increment `iteration` and `source_count` in frontmatter
+- Update `official_docs_found` if official docs were located
+
+### Step 4: Continue or Complete?
+
+**Continue** if:
+- Significant gaps remain
+- Key questions from the brief are unanswered
+- Promising leads not yet followed
+- Source count below the brief's target depth
+- Current iteration < max_iterations
+
+**Complete** if:
+- All key questions answered with citations
+- Source target met or exceeded
+- Remaining gaps are minor or out of scope
+- Diminishing returns from further searching
+
+If continuing, loop back to Step 1 for the next iteration. If complete, proceed to the Completion Process.
+
+### Completion Process
+
+1. Compile findings from state file into a structured report:
+   - Executive Summary (2-3 paragraphs, cite everything)
+   - Detailed Findings (organized by theme, not source; direct quotes blockquoted; every claim cited)
+   - Analysis (cross-cutting synthesis grounded in findings above)
+   - Limitations and Gaps (unanswered questions, source biases, whether official docs were available)
+   - Sources (numbered bibliography with [official]/[secondary] tags)
+   - Research Methodology (iterations, source count, date)
+
+2. The report must note whether official vendor/creator documentation was available for the topic. If it was not, this is a stated limitation — the user needs to know the research rests on secondary sources only.
+
+3. Write to Obsidian via `mcp__obsidian__write_note`:
+   - Path: `Research/[topic-slug].md`
+   - Include YAML frontmatter: type (deep-research), topic, date, sources count, iterations, official_docs_available (true/false), tags
+   - Every factual claim has an inline citation
+   - Full numbered bibliography at the end with [official]/[secondary] tags
+
+4. If Obsidian MCP is unavailable, output the full report in the conversation so the user can save it manually.
+
+### If max iterations reached without completion
+
+- Compile what you have into a partial report
+- Mark incomplete sections clearly
+- Add "Future Research" section listing remaining gaps
+- Still write to Obsidian
+
+## Output to Parent
+
+After completion, your return message to the parent should include:
+- Obsidian note path where the report was saved (or "output inline" if MCP unavailable)
+- Total sources consulted (with official vs secondary breakdown)
+- Total iterations used
+- Whether official vendor documentation was found
+- Any significant gaps or limitations

package/bin/install.mjs

@@ -5,7 +5,6 @@ import { join, dirname, resolve, relative } from 'node:path';
 import { homedir } from 'node:os';
 import { execSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
-import { createRequire } from 'node:module';
 
 const CLAUDE_HOME = join(homedir(), '.claude');
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
@@ -13,7 +12,32 @@ const MANIFEST_FILE = join(CLAUDE_HOME, '.claude-dev-env-manifest.json');
 const PACKAGE_NAME = 'claude-dev-env';
 
 const CONTENT_DIRECTORIES = ['rules', 'docs', 'commands', 'agents'];
-const WORKSPACE_SIBLINGS = ['claude-journal', 'claude-deep-research', 'claude-prompt-tools'];
+
+const INSTALL_GROUPS = {
+    core: {
+        description: 'Development standards, hooks, agents, commands',
+        skills: [
+            'anthropic-plan', 'everything-search', 'ingest',
+            'npm-creator', 'pr-review-responder', 'readability-review',
+            'recall', 'remember', 'rule-audit', 'rule-creator',
+            'skill-writer', 'tdd-team'
+        ],
+        includeDirectories: ['rules', 'docs', 'commands', 'agents'],
+        includeAllHooks: true,
+    },
+    prompts: {
+        description: 'Prompt engineering tools',
+        skills: ['prompt-generator', 'agent-prompt'],
+    },
+    journal: {
+        description: 'Session logging and memory',
+        skills: ['dream', 'session-log', 'session-tidy'],
+    },
+    research: {
+        description: 'Deep research and citation tools',
+        skills: ['deep-research', 'research-mode'],
+    },
+};
 
 function detectPython() {
     const candidates = [
@@ -116,74 +140,14 @@ function mergeHooks(pythonCommand) {
     return groupCount;
 }
 
-function findSiblingPackage(packageName) {
-    const workspaceRoot = resolve(PACKAGE_ROOT, '..', '..');
-    const workspacePath = join(workspaceRoot, 'packages', packageName);
-    if (existsSync(join(workspacePath, 'package.json'))) {
-        return workspacePath;
-    }
-    const require = createRequire(import.meta.url);
-    try {
-        const packageJsonPath = require.resolve(join(packageName, 'package.json'));
-        return dirname(packageJsonPath);
-    } catch { /* not found */ }
-    return null;
-}
-
-function installSiblingContent(siblingRoot, allInstalledFiles) {
-    const siblingName = JSON.parse(readFileSync(join(siblingRoot, 'package.json'), 'utf8')).name;
-    console.log(`  Installing sibling: ${siblingName}`);
-    let totalFiles = 0;
-    const skillsSource = join(siblingRoot, 'skills');
-    if (existsSync(skillsSource)) {
-        const skillDirs = readdirSync(skillsSource, { withFileTypes: true }).filter(entry => entry.isDirectory());
-        for (const skillDir of skillDirs) {
-            const stats = copyTree(join(skillsSource, skillDir.name), join(CLAUDE_HOME, 'skills', skillDir.name));
-            allInstalledFiles.push(...stats.paths);
-            totalFiles += stats.created + stats.updated;
-        }
-    }
-    const agentsSource = join(siblingRoot, 'agents');
-    if (existsSync(agentsSource)) {
-        const stats = copyTree(agentsSource, join(CLAUDE_HOME, 'agents'));
-        allInstalledFiles.push(...stats.paths);
-        totalFiles += stats.created + stats.updated;
-    }
-    const rulesSource = join(siblingRoot, 'rules');
-    if (existsSync(rulesSource)) {
-        const stats = copyTree(rulesSource, join(CLAUDE_HOME, 'rules'));
-        allInstalledFiles.push(...stats.paths);
-        totalFiles += stats.created + stats.updated;
-    }
-    const hooksSource = join(siblingRoot, 'hooks');
-    if (existsSync(hooksSource)) {
-        const filesToCopy = collectFiles(hooksSource).filter(file => !file.endsWith('hooks.json'));
-        const hooksDestination = join(CLAUDE_HOME, 'hooks');
-        for (const sourceFile of filesToCopy) {
-            const relativePath = relative(hooksSource, sourceFile);
-            const destFile = join(hooksDestination, relativePath);
-            mkdirSync(dirname(destFile), { recursive: true });
-            const existed = existsSync(destFile);
-            copyFileSync(sourceFile, destFile);
-            allInstalledFiles.push(destFile);
-            totalFiles++;
-            if (existed) {
-                console.log(`  ↻ ${join('hooks', relativePath)} (updated)`);
-            } else {
-                console.log(`  ✓ ${join('hooks', relativePath)} (new)`);
-            }
-        }
-    }
-    return totalFiles;
-}
-
 function writeManifest(installedFiles) {
     const manifest = { package: PACKAGE_NAME, version: '1.0.0', installedAt: new Date().toISOString(), files: installedFiles };
     writeFileSync(MANIFEST_FILE, JSON.stringify(manifest, null, 2) + '\n');
 }
 
-function install() {
-    console.log(`\nInstalling ${PACKAGE_NAME}...\n`);
+function install(selectedGroups) {
+    const groupLabel = selectedGroups ? `groups: ${selectedGroups.join(', ')}` : 'all';
+    console.log(`\nInstalling ${PACKAGE_NAME} (${groupLabel})...\n`);
     const pythonCommand = detectPython();
     if (!pythonCommand) {
         console.error('ERROR: Python 3 not found. Install Python 3.8+ and ensure python3, python, or py is on PATH.');
@@ -191,9 +155,21 @@ function install() {
     }
     console.log(`  Python: ${pythonCommand}`);
     mkdirSync(CLAUDE_HOME, { recursive: true });
+
+    const allowedSkills = selectedGroups
+        ? new Set(selectedGroups.flatMap(groupName => INSTALL_GROUPS[groupName].skills || []))
+        : null;
+    const allowedDirectories = selectedGroups
+        ? new Set(selectedGroups.flatMap(groupName => INSTALL_GROUPS[groupName].includeDirectories || []))
+        : null;
+    const shouldInstallHooks = selectedGroups
+        ? selectedGroups.some(groupName => INSTALL_GROUPS[groupName].includeAllHooks)
+        : true;
+
     const allInstalledFiles = [];
     const summary = {};
     for (const directory of CONTENT_DIRECTORIES) {
+        if (allowedDirectories && !allowedDirectories.has(directory)) continue;
         const sourceDir = join(PACKAGE_ROOT, directory);
         if (!existsSync(sourceDir)) continue;
         const destDir = join(CLAUDE_HOME, directory);
@@ -208,6 +184,7 @@ function install() {
         let skillsUpdated = 0;
         const skillPaths = [];
         for (const skillDir of skillDirs) {
+            if (allowedSkills && !allowedSkills.has(skillDir.name)) continue;
             const stats = copyTree(join(skillsSource, skillDir.name), join(CLAUDE_HOME, 'skills', skillDir.name));
             skillsCreated += stats.created;
             skillsUpdated += stats.updated;
@@ -216,36 +193,28 @@ function install() {
         summary.skills = { created: skillsCreated, updated: skillsUpdated, paths: skillPaths };
         allInstalledFiles.push(...skillPaths);
     }
-    let siblingCount = 0;
-    for (const siblingName of WORKSPACE_SIBLINGS) {
-        const siblingRoot = findSiblingPackage(siblingName);
-        if (siblingRoot) {
-            siblingCount += installSiblingContent(siblingRoot, allInstalledFiles);
-        }
-    }
-    if (siblingCount > 0) {
-        summary.siblings = siblingCount;
-    }
-    const hooksSource = join(PACKAGE_ROOT, 'hooks');
-    if (existsSync(hooksSource)) {
-        const hooksDestination = join(CLAUDE_HOME, 'hooks');
-        const filesToCopy = collectFiles(hooksSource).filter(file => !file.endsWith('hooks.json'));
-        let hooksCreated = 0;
-        let hooksUpdated = 0;
-        for (const sourceFile of filesToCopy) {
-            const relativePath = relative(hooksSource, sourceFile);
-            const destFile = join(hooksDestination, relativePath);
-            mkdirSync(dirname(destFile), { recursive: true });
-            const existed = existsSync(destFile);
-            copyFileSync(sourceFile, destFile);
-            allInstalledFiles.push(destFile);
-            if (existed) { hooksUpdated++; } else { hooksCreated++; }
+    if (shouldInstallHooks) {
+        const hooksSource = join(PACKAGE_ROOT, 'hooks');
+        if (existsSync(hooksSource)) {
+            const hooksDestination = join(CLAUDE_HOME, 'hooks');
+            const filesToCopy = collectFiles(hooksSource).filter(file => !file.endsWith('hooks.json'));
+            let hooksCreated = 0;
+            let hooksUpdated = 0;
+            for (const sourceFile of filesToCopy) {
+                const relativePath = relative(hooksSource, sourceFile);
+                const destFile = join(hooksDestination, relativePath);
+                mkdirSync(dirname(destFile), { recursive: true });
+                const existed = existsSync(destFile);
+                copyFileSync(sourceFile, destFile);
+                allInstalledFiles.push(destFile);
+                if (existed) { hooksUpdated++; } else { hooksCreated++; }
+            }
+            summary.hookFiles = { created: hooksCreated, updated: hooksUpdated };
+            console.log(`  Hook files: ${hooksCreated} new, ${hooksUpdated} updated`);
+            const groupCount = mergeHooks(pythonCommand);
+            summary.hookGroups = groupCount;
+            console.log(`  Hook groups: ${groupCount} merged into settings.json`);
         }
-        summary.hookFiles = { created: hooksCreated, updated: hooksUpdated };
-        console.log(`  Hook files: ${hooksCreated} new, ${hooksUpdated} updated`);
-        const groupCount = mergeHooks(pythonCommand);
-        summary.hookGroups = groupCount;
-        console.log(`  Hook groups: ${groupCount} merged into settings.json`);
     }
     writeManifest(allInstalledFiles);
     console.log(`\nInstalled ${PACKAGE_NAME}:`);
@@ -259,9 +228,6 @@ function install() {
         const { created, updated } = summary.skills;
         console.log(`  skills: ${created + updated} files (${created} new, ${updated} updated)`);
     }
-    if (summary.siblings) {
-        console.log(`  workspace siblings: ${summary.siblings} files`);
-    }
     if (summary.hookFiles) {
         console.log(`  hooks: ${summary.hookFiles.created + summary.hookFiles.updated} files, ${summary.hookGroups} groups in settings.json`);
     }
@@ -319,15 +285,45 @@ function printHelp() {
 ${PACKAGE_NAME} - Claude Code development standards installer
 
 Usage:
-  npx ${PACKAGE_NAME}              Install rules, hooks, agents, commands, skills
-  npx ${PACKAGE_NAME} --uninstall  Remove installed files and hooks
+  npx ${PACKAGE_NAME}              Install everything
+  npx ${PACKAGE_NAME} --only X     Install specific groups
+  npx ${PACKAGE_NAME} --uninstall  Remove installed files
   npx ${PACKAGE_NAME} --help       Show this help
 
+Groups:
+  core      Development standards, hooks, agents, commands
+  prompts   Prompt engineering tools
+  journal   Session logging and memory
+  research  Deep research and citation tools
+
+Examples:
+  npx ${PACKAGE_NAME} --only prompts
+  npx ${PACKAGE_NAME} --only prompts,research
+
 Install location: ~/.claude/
 `);
 }
 
 const args = process.argv.slice(2);
-if (args.includes('--help') || args.includes('-h')) printHelp();
-else if (args.includes('--uninstall')) uninstall();
-else install();
+if (args.includes('--help') || args.includes('-h')) {
+    printHelp();
+} else if (args.includes('--uninstall')) {
+    uninstall();
+} else {
+    const onlyIndex = args.indexOf('--only');
+    let selectedGroups = null;
+    if (onlyIndex !== -1) {
+        const onlyValue = args[onlyIndex + 1];
+        if (!onlyValue || onlyValue.startsWith('--')) {
+            console.error(`ERROR: --only requires a comma-separated list of groups.\nAvailable groups: ${Object.keys(INSTALL_GROUPS).join(', ')}`);
+            process.exit(1);
+        }
+        selectedGroups = onlyValue.split(',').map(name => name.trim());
+        const invalidGroups = selectedGroups.filter(name => !INSTALL_GROUPS[name]);
+        if (invalidGroups.length > 0) {
+            console.error(`ERROR: Unknown group(s): ${invalidGroups.join(', ')}\nAvailable groups: ${Object.keys(INSTALL_GROUPS).join(', ')}`);
+            process.exit(1);
+        }
+    }
+    install(selectedGroups);
+}

package/hooks/HOOK_SPECS_PROMPT_WORKFLOW.md

@@ -0,0 +1,68 @@
+# Prompt Workflow Hook Specs
+
+Deterministic runtime gates for prompt workflows.
+
+## Gate: Execution Intent (PreToolUse Task/Agent)
+
+- Hook: `hooks/blocking/agent-execution-intent-gate.py`
+- Event: `PreToolUse`
+- Matcher: `Task|Agent`
+- Fail condition:
+  - Missing structured execution intent contract field:
+    - `tool_input.execution_intent: explicit|execute|delegate`, or
+    - `tool_input.execution_intent_explicit: true`, or
+    - `tool_input.metadata.execution_intent: explicit|execute|delegate`
+  - Missing required scope anchors in launch payload (always enforced when execution launch is evaluated)
+- Compatibility fallback:
+  - Text markers are only accepted when `PROMPT_WORKFLOW_ALLOW_TEXT_INTENT_FALLBACK=1` is set.
+  - Fallback usage is logged to stderr.
+- Action: `deny` with concrete missing requirement list.
+
+## Gate: Leakage + Checklist + Scope (Stop)
+
+- Hook: `hooks/blocking/prompt-workflow-stop-guard.py`
+- Event: `Stop`
+- Fail condition:
+  - Raw internal refinement object appears in assistant output without explicit debug intent
+  - Prompt-workflow response detected but deterministic checklist container is missing
+  - Prompt-workflow response detected and required deterministic checklist rows are missing
+  - Prompt-workflow response detected and required scope anchors are missing
+  - Prompt-workflow response detected and runtime context-control signals are missing
+  - Scope-bound text uses banned ambiguous scope terms
+- Action: `block` with correction reason.
+
+## Required Scope Anchors
+
+- `target_local_roots`
+- `target_canonical_roots`
+- `target_file_globs`
+- `comparison_basis`
+- `completion_boundary`
+
+## Required Deterministic Checklist Rows
+
+- `structured_scoped_instructions`
+- `sequential_steps_present`
+- `positive_framing`
+- `acceptance_criteria_defined`
+- `safety_reversibility_language`
+- `no_destructive_shortcuts_guidance`
+- `concrete_output_contract`
+- `scope_boundary_present`
+- `explicit_scope_anchors_present`
+- `all_instructions_artifact_bound`
+- `no_ambiguous_scope_terms`
+- `completion_boundary_measurable`
+- `citation_grounding_policy_present`
+- `source_priority_rules_present`
+
+## Runtime Context-Control Signals
+
+- `base_minimal_instruction_layer: true`
+- `on_demand_skill_loading: true`
+
+These two signals are runtime-checked by the Stop guard whenever a prompt-workflow response is detected.
+
+## Deterministic Boundary
+
+These hooks enforce only structural/runtime checks. Semantic quality remains in auditor layer.

package/hooks/blocking/agent-execution-intent-gate.py

@@ -0,0 +1,83 @@
+#!/usr/bin/env python3
+"""PreToolUse gate for Task/Agent execution intent and scope anchors."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+from prompt_workflow_gate_core import (
+    has_explicit_execution_intent,
+    has_structured_execution_intent,
+    missing_scope_anchors,
+)
+
+
+def _deny(reason: str) -> None:
+    response = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": reason,
+        }
+    }
+    print(json.dumps(response))
+
+
+def main() -> None:
+    try:
+        hook_input = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    tool_name = str(hook_input.get("tool_name", ""))
+    if tool_name not in {"Task", "Agent"}:
+        sys.exit(0)
+
+    tool_input = hook_input.get("tool_input", {})
+    prompt_text = str(tool_input.get("prompt", ""))
+    description = str(tool_input.get("description", ""))
+    combined_text = f"{description}\n{prompt_text}"
+
+    if not has_structured_execution_intent(tool_input):
+        allow_text_fallback = os.getenv(
+            "PROMPT_WORKFLOW_ALLOW_TEXT_INTENT_FALLBACK", ""
+        ).strip().lower() in {"1", "true", "yes"}
+        text_intent_detected = has_explicit_execution_intent(combined_text)
+        if allow_text_fallback and text_intent_detected:
+            print(
+                "PROMPT-WORKFLOW GATE: compatibility text-intent fallback used; "
+                "structured execution intent contract should be provided.",
+                file=sys.stderr,
+            )
+        else:
+            fallback_note = ""
+            if text_intent_detected:
+                print(
+                    "PROMPT-WORKFLOW GATE: text intent marker detected without structured "
+                    "execution intent contract.",
+                    file=sys.stderr,
+                )
+                fallback_note = " Legacy text marker was detected but is not sufficient."
+            _deny(
+                "BLOCKED: Missing structured execution intent signal for Agent/Task launch. "
+                "Provide `tool_input.execution_intent: explicit` or "
+                "`tool_input.execution_intent_explicit: true`."
+                + fallback_note
+            )
+            sys.exit(0)
+
+    missing_anchors = missing_scope_anchors(combined_text)
+    if missing_anchors:
+        _deny(
+            "BLOCKED: Scope anchors missing for prompt workflow execution: "
+            + ", ".join(missing_anchors)
+        )
+        sys.exit(0)
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()