context-detection

# Context Detection Skill ## Scope: this skill maps EVIDENCE to STACK. It does not map stack to skill The line matters, and it is the whole reason this file was rewritten. | Question | Answered in | |---|---| | Which stacks is this repo built from, and what proves it? | **here** | | Which paths should agent X read for task Y? | [`references/loadout-rules.md`](references/loadout-rules.md) | | What shape does the emitted artifact take? | [`references/context-schema.md`](references/context-schema.md) | This file used to answer all three. It carried a bash `generate_skill_paths()` and a `map_stacks_to_skills()` table, and `plugins/dev/agents/stack-detector.md` carried the same mapping again in XML. Two hand-maintained copies, both loaded on nearly every `dev` entry point — this skill is preloaded by ten commands — so when one went stale, it went stale twice. A skill path that had never existed shipped in both. **Both copies are gone.** Stack→skill mapping now has exactly one home, `references/loadout-rules.md`, and skill paths are derived from the filesystem at detection time rather than recalled from a table. Do not reintroduce a table here, in any language, in any fence. ## Quick Start: Skill Discovery Script Run the helper script to discover ALL skills available to a project: ```bash node "${CLAUDE_PLUGIN_ROOT}/skills/context-detection/scripts/discover-skills.js" "$(pwd)" ``` This searches all 7 official Claude Code skill locations: 1. Personal: `~/.claude/skills/` 2. Project: `.claude/skills/` 3. Nested (monorepos): `**/.claude/skills/` 4. Legacy commands: `.claude/commands/` 5. Marketplace plugins: `~/.claude/plugins/marketplaces/{m}/plugins/{p}/skills/` 6. Local plugins: `.claude-plugin/skills/`, `plugins/*/skills/` 7. Enterprise (managed settings) **Output:** JSON with summary stats and full skill metadata. For detailed documentation on the script, see [scripts/discover-skills.js](scripts/discover-skills.js). --- ## Overview The context detection skill provides systematic patterns for analyzing any project to determine its technology stack(s). It enables the dev plugin to auto-load appropriate framework-specific skills based on what's actually in the project. **Key Innovation:** Multi-stack detection for fullstack projects (e.g., React + Go). --- ## Detection Priority Detection follows a priority order from most explicit to most inferred: ### 1. Explicit User Preference (Highest Priority) **Source:** `.claude/settings.json` ```json { "pluginSettings": { "dev": { "stack": ["react-typescript", "golang"] } } } ``` **When to use:** - User wants to override auto-detection - Project has ambiguous structure - Custom stack combinations ### 2. Current File Context **Source:** File extension of current editing context ```yaml # extension -> stack id. Stack ids only; which SKILL a stack implies is not decided here. extension_mappings: ".tsx": ["react-typescript"] ".vue": ["vue-typescript"] ".go": ["golang"] ".dingo": ["dingo", "golang"] # Dingo transpiles to Go, so both ".rs": ["rust"] ".py": ["python"] ``` **When to use:** - User is editing a specific file - Immediate context for implementation - Quick detection without full project scan ### 3. Configuration Files (Primary Detection) **Source:** Project configuration files ```yaml # config file -> stack id + mode. No skill names: see references/loadout-rules.md. config_file_patterns: package.json (react): check: "dependencies.react or devDependencies.react exists" stacks: ["react-typescript"] mode: "frontend" package.json (vue): check: "dependencies.vue exists" stacks: ["vue-typescript"] mode: "frontend" go.mod: check: "file exists" stacks: ["golang"] mode: "backend" go.mod + *.dingo: check: "go.mod exists AND any .dingo file present" stacks: ["dingo", "golang"] mode: "backend" note: "Dingo transpiles to Go, so a Dingo repo is also a Go repo" Cargo.toml: check: "file exists" stacks: ["rust"] mode: "backend" pyproject.toml: check: "file exists" stacks: ["python"] mode: "backend" bun.lock or bun.lockb: check: "either lockfile exists AND no react/vue in package.json (bun.lock is the text lockfile Bun writes by default; bun.lockb is the older binary one)" stacks: ["bunjs"] mode: "backend" ``` **When to use:** - First time analyzing a project - Most reliable detection method - Determine versions and dependencies ### 4. Directory Structure Patterns (Supporting Evidence) **Source:** Common directory layouts ```yaml directory_patterns: "src/routes/": indicator: "React Router structure" stacks: ["react-typescript"] "src/components/": indicator: "Component-based frontend" stacks: ["react-typescript", "vue-typescript"] "cmd/": indicator: "Go standard project layout" stacks: ["golang"] "src/main.rs": indicator: "Rust binary crate" stacks: ["rust"] "frontend/": indicator: "Separate frontend directory (fullstack)" note: "Check for backend/ as well" "backend/": indicator: "Separate backend directory (fullstack)" note: "Check for frontend/ as well" ``` **When to use:** - Confirming config file detection - Identifying fullstack projects - Disambiguating multi-purpose projects --- ## Multi-Stack Detection Algorithm **CRITICAL:** Always check for MULTIPLE stacks. Projects can be fullstack. ```bash # Step 1: Find ALL config files (not just first match) find_all_configs() { configs=() [ -f "package.json" ] && configs+=("package.json") [ -f "go.mod" ] && configs+=("go.mod") [ -f "Cargo.toml" ] && configs+=("Cargo.toml") [ -f "pyproject.toml" ] && configs+=("pyproject.toml") [ -f "bun.lock" ] && configs+=("bun.lock") [ -f "bun.lockb" ] && configs+=("bun.lockb") # Check for Dingo files (go.mod must also exist) # Note: "dingo" is a detection indicator, not an actual config file name if [ -f "go.mod" ] && find . -name "*.dingo" -type f ! -path "./.git/*" ! -path "./node_modules/*" ! -path "./vendor/*" -print -quit | grep -q .; then configs+=("dingo") fi echo "${configs[@]}" } # Step 2: Analyze EACH config file analyze_all_configs() { local detected_stacks=() # Check package.json if [ -f "package.json" ]; then if grep -q '"react"' package.json; then detected_stacks+=("react-typescript") elif grep -q '"vue"' package.json; then detected_stacks+=("vue-typescript") fi fi # Check go.mod (and optionally Dingo) if [ -f "go.mod" ]; then # Check if this is a Dingo project if find . -name "*.dingo" -type f ! -path "./.git/*" ! -path "./node_modules/*" ! -path "./vendor/*" -print -quit | grep -q .; then detected_stacks+=("dingo") # Dingo always co-loads golang detected_stacks+=("golang") else detected_stacks+=("golang") fi fi # Check Cargo.toml if [ -f "Cargo.toml" ]; then detected_stacks+=("rust") fi # Check pyproject.toml if [ -f "pyproject.toml" ]; then detected_stacks+=("python") fi # Check for a Bun lockfile, text or binary (only if NOT frontend) if { [ -f "bun.lock" ] || [ -f "bun.lockb" ]; } && ! grep -q '"react"\|"vue"' package.json 2>/dev/null; then detected_stacks+=("bunjs") fi echo "${detected_stacks[@]}" } # Step 3: Determine mode determine_mode() { local stacks=("$@") local has_frontend=false local has_backend=false for stack in "${stacks[@]}"; do case "$stack" in react-typescript|vue-typescript) has_frontend=true ;; golang|rust|python|bunjs|dingo) has_backend=true ;; esac done if [ "$has_frontend" = true ] && [ "$has_backend" = true ]; then echo "fullstack" elif [ "$has_frontend" = true ]; then echo "frontend" elif [ "$has_backend" = true ]; then echo "backend" else echo "unknown" fi } # Step 4: Complete detection # # NOTE: there is deliberately no `map_stacks_to_skills` step here. Turning a stack list # into a reading list is NOT this file's job — see references/loadout-rules.md. A copy of # that mapping used to live right here, and a second copy lived in the stack-detector # agent; keeping them in sync failed, and a dead skill path shipped in both. detect_project_stack() { # Check explicit preference first local explicit_stack=$(jq -r '.pluginSettings.dev.stack // empty' .claude/settings.json 2>/dev/null) if [ -n "$explicit_stack" ]; then echo "Using explicit stack from .claude/settings.json" return fi # Auto-detect all stacks local detected_stacks=($(analyze_all_configs)) if [ ${#detected_stacks[@]} -eq 0 ]; then echo "ERROR: No stack detected" return 1 fi local mode=$(determine_mode "${detected_stacks[@]}") echo "Detected: ${detected_stacks[*]}" echo "Mode: $mode" } ``` --- ## Framework-Specific Detection ### React Detection ```bash detect_react() { # Check package.json if [ -f "package.json" ]; then # React in dependencies or devDependencies if jq -e '.dependencies.react // .devDependencies.react' package.json >/dev/null 2>&1; then # Check for TypeScript local has_typescript=false if jq -e '.dependencies["@types/react"] // .devDependencies["@types/react"]' package.json >/dev/null 2>&1; then has_typescript=true fi # Get version local react_version=$(jq -r '.dependencies.react // .devDependencies.react' package.json | sed 's/[^0-9.]//g') echo "react-typescript" echo "version: $react_version" echo "typescript: $has_typescript" return 0 fi fi return 1 } ``` ### Vue Detection ```bash detect_vue() { if [ -f "package.json" ]; then if jq -e '.dependencies.vue' package.json >/dev/null 2>&1; then local vue_version=$(jq -r '.dependencies.vue' package.json | sed 's/[^0-9.]//g') echo "vue-typescript" echo "version: $vue_version" return 0 fi fi return 1 } ``` ### Go Detection ```bash detect_go() { if [ -f "go.mod" ]; then local go_version=$(grep '^go ' go.mod | awk '{print $2}') local module_name=$(grep '^module ' go.mod | awk '{print $2}') echo "golang" echo "version: $go_version" echo "module: $module_name" return 0 fi return 1 } ``` ### Rust Detection ```bash detect_rust() { if [ -f "Cargo.toml" ]; then local package_name=$(grep '^\[package\]' -A 5 Cargo.toml | grep '^name' | cut -d'"' -f2) local edition=$(grep '^\[package\]' -A 5 Cargo.toml | grep '^edition' | cut -d'"' -f2) echo "rust" echo "edition: $edition" echo "package: $package_name" return 0 fi return 1 } ``` ### Python Detection ```bash