diff --git a/.ai-workspace/scripts/skill-suggest.sh b/.ai-workspace/scripts/skill-suggest.sh old mode 100755 new mode 100644 index c910bd7..0661b7c --- a/.ai-workspace/scripts/skill-suggest.sh +++ b/.ai-workspace/scripts/skill-suggest.sh @@ -14,7 +14,7 @@ SKILLS="" # Check file extensions and paths if echo "$FILE" | grep -qiE 'test_|_test\.py|tests/|\.py$'; then - SKILLS="$SKILLS python-conventions" + SKILLS="$SKILLS python-patterns" fi if echo "$FILE" | grep -qiE '\.env|\.gitignore|secret|credential|token'; then @@ -22,16 +22,16 @@ if echo "$FILE" | grep -qiE '\.env|\.gitignore|secret|credential|token'; then fi if echo "$FILE" | grep -qiE 'pipeline|fetch_|group_|filter_|summarize_|categorize_'; then - SKILLS="$SKILLS data-pipeline-patterns" + SKILLS="$SKILLS python-patterns" fi if echo "$FILE" | grep -qiE 'api|client|request|fetch'; then - SKILLS="$SKILLS python-conventions" + SKILLS="$SKILLS python-patterns" fi # Check command content if echo "$CMD" | grep -qiE 'pytest|test|coverage'; then - SKILLS="$SKILLS python-conventions" + SKILLS="$SKILLS python-patterns" fi if echo "$CMD" | grep -qiE 'git (commit|push|merge|rebase)'; then diff --git a/.ai-workspace/tests/test-hooks.sh b/.ai-workspace/tests/test-hooks.sh index b98ac7a..df77f6f 100644 --- a/.ai-workspace/tests/test-hooks.sh +++ b/.ai-workspace/tests/test-hooks.sh @@ -62,22 +62,22 @@ fi # SKILL SUGGEST HOOK TESTS # ============================================================ -# Test 4: Python file → python-conventions +# Test 4: Python file → python-patterns export CLAUDE_TOOL_INPUT='{"file_path": "/home/user/main.py"}' OUTPUT=$(bash "$PROJECT_DIR/.ai-workspace/scripts/skill-suggest.sh" 2>&1) -if echo "$OUTPUT" | grep -q "python-conventions"; then - pass "Skill suggest: .py → python-conventions" +if echo "$OUTPUT" | grep -q "python-patterns"; then + pass "Skill suggest: .py → python-patterns" else - fail "Skill suggest: .py → python-conventions" "Got: $OUTPUT" + fail "Skill suggest: .py → python-patterns" "Got: $OUTPUT" fi -# Test 5: Test file → python-conventions +# Test 5: Test file → python-patterns export CLAUDE_TOOL_INPUT='{"file_path": "/home/user/tests/test_main.py"}' OUTPUT=$(bash "$PROJECT_DIR/.ai-workspace/scripts/skill-suggest.sh" 2>&1) -if echo "$OUTPUT" | grep -q "python-conventions"; then - pass "Skill suggest: test file → python-conventions" +if echo "$OUTPUT" | grep -q "python-patterns"; then + pass "Skill suggest: test file → python-patterns" else - fail "Skill suggest: test file → python-conventions" "Got: $OUTPUT" + fail "Skill suggest: test file → python-patterns" "Got: $OUTPUT" fi # Test 6: .env file → security-check @@ -89,13 +89,13 @@ else fail "Skill suggest: .env → security-check" "Got: $OUTPUT" fi -# Test 7: Pipeline file → data-pipeline-patterns +# Test 7: Pipeline file → python-patterns export CLAUDE_TOOL_INPUT='{"file_path": "/home/user/scripts/fetch_data.py"}' OUTPUT=$(bash "$PROJECT_DIR/.ai-workspace/scripts/skill-suggest.sh" 2>&1) -if echo "$OUTPUT" | grep -q "data-pipeline-patterns"; then - pass "Skill suggest: pipeline file → data-pipeline-patterns" +if echo "$OUTPUT" | grep -q "python-patterns"; then + pass "Skill suggest: pipeline file → python-patterns" else - fail "Skill suggest: pipeline file → data-pipeline-patterns" "Got: $OUTPUT" + fail "Skill suggest: pipeline file → python-patterns" "Got: $OUTPUT" fi # Test 8: Git command → security-check diff --git a/.claude/commands/check-code.md b/.claude/commands/check-code.md index c39bfa2..ec80ab0 100644 --- a/.claude/commands/check-code.md +++ b/.claude/commands/check-code.md @@ -1,10 +1,10 @@ --- -description: "Check code quality and run linting" +description: "Run a lightweight Python lint and format check. Use /verify for the full environment, type, lint, and test workflow." --- -# Check Code +# Check Code (lightweight) -Look at the code in the current directory or the path provided by the user. +Look at the Python code in the current directory or the path provided by the user. This is the fast feedback command; use `/verify` for the complete check. Run these checks: 1. Run `ruff check .` to find linting issues diff --git a/.claude/commands/test-coverage.md b/.claude/commands/test-coverage.md index f5c8e50..bb00292 100644 --- a/.claude/commands/test-coverage.md +++ b/.claude/commands/test-coverage.md @@ -1,5 +1,5 @@ --- -description: "Analyze test coverage, identify gaps, and generate missing tests to reach 80%+ coverage." +description: "Analyze test coverage, identify gaps, and generate focused missing tests. Respects the project's configured coverage target when one exists." --- # Test Coverage Command @@ -75,7 +75,7 @@ For each under-covered file, generate tests following this priority: 1. Run the full test suite — all tests must pass 2. Re-run coverage — verify improvement -3. If still below 80%, repeat Step 3 for remaining gaps +3. If still below the project's configured target, repeat Step 3 for the highest-value remaining gaps. If no target is configured, report the measured coverage without imposing an arbitrary threshold. ### Step 5: Report diff --git a/.claude/commands/toolkit.md b/.claude/commands/toolkit.md index 0dc80b7..769ada0 100644 --- a/.claude/commands/toolkit.md +++ b/.claude/commands/toolkit.md @@ -90,7 +90,7 @@ Based on what the user is currently doing, suggest specific tools: → "New to this repo? Ask me to explain how the project works and I'll onboard you." **If they're in a data pipeline project (Python + JSON/YAML + API calls):** -→ "This looks like a data pipeline. `data-pipeline-patterns` and `python-conventions` will activate automatically when you write pipeline code." +→ "This looks like a data pipeline. `python-patterns` will activate automatically when you write pipeline code." **If there's a `.mcp.json` file:** → "MCP is configured here. The `mcp-patterns` agent-doc will help if you build or modify MCP servers." @@ -99,7 +99,7 @@ Based on what the user is currently doing, suggest specific tools: → "Found tests. Run `/test-coverage` to see what's untested." **If there are failing tests or recent errors:** -→ "Looks like something is broken. The `systematic-debugging` skill will activate — it follows a structured root cause analysis instead of guessing." +→ "Looks like something is broken. Use `/env-check` first, then `/verify` after applying a fix." **If files are large or complex (>300 lines, deep nesting):** → "Some files here are getting complex. When you're ready to clean up, `refactoring-patterns` will guide measurement-driven refactoring." diff --git a/GUIDE.md b/GUIDE.md index 06fd01a..0320629 100644 --- a/GUIDE.md +++ b/GUIDE.md @@ -79,9 +79,8 @@ Skills activate on their own — you just get better results. They live in `skil | Skill | Purpose | When it activates | |-------|---------|-------------------| -| `python-conventions` | Dotenv conventions, API client rules, LLM response parsing, TDD workflow, pytest patterns | When you edit Python files or API client code | +| `python-patterns` | Dotenv conventions, API client rules, LLM response parsing, TDD workflow, pytest patterns | When you edit Python files or API client code | | `security-check` | Credential leak detection (API keys for GitHub, Stripe, AWS, etc.), insecure code patterns (eval, pickle, shell injection), LLM-specific risks | When you edit code that touches credentials, APIs, or security-sensitive patterns | -| `data-pipeline-patterns` | Pipeline stage design, data validation, circuit breakers, checkpoint/resume, debugging | When you work on pipeline scripts or data processing code | | `refactoring-patterns` | Measurement-driven refactoring — profile before, measure after, keep only if metrics improve. Bulk mode for 10+ files. | When you say "refactor", "clean up", or code has high complexity | | `verification-loop` | Unified engine behind `/verify`, `/quality-gate` — environment, types, lint, tests, review, security | When you invoke /verify or /quality-gate | | `brainstorming` | Design exploration before implementation — asks questions, proposes approaches, presents design for approval | When creative/design work is detected | diff --git a/README.md b/README.md index 3e5cc8f..6b05af9 100644 --- a/README.md +++ b/README.md @@ -45,10 +45,9 @@ Skills are knowledge that Claude carries in the background. You don't trigger th | Skill | What it does | |-------|-------------| | `security-check` | Detects credential leaks, insecure patterns, LLM-specific risks | -| `python-conventions` | Dotenv conventions, API client rules, TDD workflow | -| `data-pipeline-patterns` | Pipeline stage design, validation, circuit breakers | +| `python-patterns` | Dotenv conventions, API clients, LLM parsing, testing, and pipelines | | `refactoring-patterns` | Measurement-driven refactoring with before/after metrics | -| `verification-loop` | Powers `/verify`, `/quality-gate` | +| `verification-loop` | Powers `/verify`, `/quality-gate` (invoked on demand) | | `brainstorming` | Design exploration before implementation | ### Commands (you trigger these) diff --git a/ai-workspace.toml b/ai-workspace.toml index ef63240..7d45d5d 100644 --- a/ai-workspace.toml +++ b/ai-workspace.toml @@ -37,9 +37,9 @@ ai-engineer-review = [] # standalone command # Set to false if this skill should only load when explicitly invoked [skills.auto-activate] security-check = true # Triggers when editing code that handles credentials/APIs -verification-loop = true # Powers multiple commands, loads on-demand +verification-loop = false # Invoked explicitly by /verify and /quality-gate python-patterns = true # Triggers when editing Python code refactoring-patterns = true # Triggers when refactoring brainstorming = true # Triggers when user asks for design/planning -cost-speed-meter = true # Tracks all command execution automatically +cost-speed-meter = false # Use its scripts explicitly when measuring commands update-docs = false # Activated via /update-docs command diff --git a/commands/check-code/command.md b/commands/check-code/command.md index c39bfa2..ec80ab0 100644 --- a/commands/check-code/command.md +++ b/commands/check-code/command.md @@ -1,10 +1,10 @@ --- -description: "Check code quality and run linting" +description: "Run a lightweight Python lint and format check. Use /verify for the full environment, type, lint, and test workflow." --- -# Check Code +# Check Code (lightweight) -Look at the code in the current directory or the path provided by the user. +Look at the Python code in the current directory or the path provided by the user. This is the fast feedback command; use `/verify` for the complete check. Run these checks: 1. Run `ruff check .` to find linting issues diff --git a/commands/test-coverage/command.md b/commands/test-coverage/command.md index f5c8e50..bb00292 100644 --- a/commands/test-coverage/command.md +++ b/commands/test-coverage/command.md @@ -1,5 +1,5 @@ --- -description: "Analyze test coverage, identify gaps, and generate missing tests to reach 80%+ coverage." +description: "Analyze test coverage, identify gaps, and generate focused missing tests. Respects the project's configured coverage target when one exists." --- # Test Coverage Command @@ -75,7 +75,7 @@ For each under-covered file, generate tests following this priority: 1. Run the full test suite — all tests must pass 2. Re-run coverage — verify improvement -3. If still below 80%, repeat Step 3 for remaining gaps +3. If still below the project's configured target, repeat Step 3 for the highest-value remaining gaps. If no target is configured, report the measured coverage without imposing an arbitrary threshold. ### Step 5: Report diff --git a/commands/toolkit/command.md b/commands/toolkit/command.md index 0dc80b7..769ada0 100644 --- a/commands/toolkit/command.md +++ b/commands/toolkit/command.md @@ -90,7 +90,7 @@ Based on what the user is currently doing, suggest specific tools: → "New to this repo? Ask me to explain how the project works and I'll onboard you." **If they're in a data pipeline project (Python + JSON/YAML + API calls):** -→ "This looks like a data pipeline. `data-pipeline-patterns` and `python-conventions` will activate automatically when you write pipeline code." +→ "This looks like a data pipeline. `python-patterns` will activate automatically when you write pipeline code." **If there's a `.mcp.json` file:** → "MCP is configured here. The `mcp-patterns` agent-doc will help if you build or modify MCP servers." @@ -99,7 +99,7 @@ Based on what the user is currently doing, suggest specific tools: → "Found tests. Run `/test-coverage` to see what's untested." **If there are failing tests or recent errors:** -→ "Looks like something is broken. The `systematic-debugging` skill will activate — it follows a structured root cause analysis instead of guessing." +→ "Looks like something is broken. Use `/env-check` first, then `/verify` after applying a fix." **If files are large or complex (>300 lines, deep nesting):** → "Some files here are getting complex. When you're ready to clean up, `refactoring-patterns` will guide measurement-driven refactoring." diff --git a/skills/ci-guard/SKILL.md b/skills/ci-guard/SKILL.md index 7c4f175..9788f80 100644 --- a/skills/ci-guard/SKILL.md +++ b/skills/ci-guard/SKILL.md @@ -6,7 +6,7 @@ description: Use when starting work in a repository under repositories/ that may # CI Guard -Every repository using this basecamp should have CI unless explicitly marked as research. This skill checks for CI configuration and alerts when it's missing. +Repositories benefit from CI, but this skill is advisory. It checks for CI configuration and alerts when it is missing, while allowing research, prototypes, and intentionally local projects. ## When to Activate diff --git a/skills/cost-speed-meter/SKILL.md b/skills/cost-speed-meter/SKILL.md index 9ac430b..66284ea 100644 --- a/skills/cost-speed-meter/SKILL.md +++ b/skills/cost-speed-meter/SKILL.md @@ -1,17 +1,17 @@ --- name: cost-speed-meter -description: Track command execution times and suggest faster paths. After tests/builds/lint, shows execution cost and recommends fast-path alternatives (unit tests vs integration, cached builds). For feedback loop optimization and proving optimizations worked. +description: Use when the user asks to measure command execution time or optimize a feedback loop. Records explicit measurements and recommends faster alternatives such as unit tests versus integration tests. It is opt-in; it does not run on every command. --- # Cost & Speed Meter Track execution time. Suggest faster paths. Prove optimizations worked. -Every bash command is timed and stored. Across sessions, you see trends: is the test suite slower? Did that optimization help? Should you run unit tests instead of full integration tests for faster feedback? +Measure only commands the user asks to compare. Across sessions, the optional metrics file can show trends without adding noise or overhead to normal work. ## When to Use -- User runs tests, builds, or lint commands — timing is tracked automatically +- User asks to measure tests, builds, or lint commands - User asks: "is this slow?", "how long did that take?", "what's the slowest operation?" - User asks: "what's a faster way to do this?", "what's the quick feedback loop?" - User is optimizing something — measure before, optimize, measure after to prove it worked @@ -29,22 +29,13 @@ Every bash command is timed and stored. Across sessions, you see trends: is the ## Output -### Session Status (automatic) - -After relevant commands, status line shows: -``` -[METRICS: tests 45s | build 8s | slowest: integration tests] -``` - ### Command Reports On demand: ``` -/metrics Show this session's measurements -/metrics-report Weekly summary (last 7 days, trends) -/metrics-slowest Which operations cost the most time -/metrics-recommend Suggest faster paths (unit tests vs integration) +Use `skills/cost-speed-meter/meter.sh show` for current measurements or +`skills/cost-speed-meter/meter.sh report` for a weekly summary. ``` ## Fast-Path Recommendations @@ -167,8 +158,8 @@ if "Cargo.toml" with [dev-dependencies]: ## Behavioral Rules -- **Always track** — every bash command is timed (overhead: <10ms) +- **Opt-in only** — never intercept or time unrelated commands - **No alerts** — just data, no noise - **Trends** — report 7-day moving average, flag +10% growth - **Respect RTK** — if RTK is filtering, meter still gets accurate time -- **No modifications** — meter reads, doesn't change command output +- **No command interception** — measurement is explicit and does not change command output diff --git a/skills/cost-speed-meter/meter-hook.sh b/skills/cost-speed-meter/meter-hook.sh index 036ec26..ab633e9 100644 --- a/skills/cost-speed-meter/meter-hook.sh +++ b/skills/cost-speed-meter/meter-hook.sh @@ -1,7 +1,7 @@ #!/bin/bash -# Auto-tracking hook for cost-speed-meter -# Measures execution time of test, build, lint, and git commands -# Called by Claude Code PreToolUse hook +# Optional suggestion hook for cost-speed-meter. +# It is intentionally not installed as a global command hook: PreToolUse +# cannot measure the command that runs after it. Use meter.sh explicitly. METRICS_DIR="${CLAUDE_PROJECT_DIR}/.claude" METRICS_FILE="${METRICS_DIR}/metrics.json" @@ -55,12 +55,4 @@ category=$(categorize_cmd "$CMD") # Only track if metrics file exists (repo has initialized) [[ ! -f "$METRICS_FILE" ]] && exit 0 -# Record timing in background (don't block the command) -{ - start_time=$(date +%s.%N) - # Actual command runs via Claude Code (not here) - # We just record what we know - sleep 0.1 # placeholder; actual timing comes from Claude Code measurement -} & - exit 0 diff --git a/skills/cost-speed-meter/meter.sh b/skills/cost-speed-meter/meter.sh old mode 100755 new mode 100644 index 9284c44..1722a10 --- a/skills/cost-speed-meter/meter.sh +++ b/skills/cost-speed-meter/meter.sh @@ -93,7 +93,7 @@ PYTHON show_current() { [[ ! -f "$METRICS_FILE" ]] && { echo "No metrics yet. Run commands first."; return; } - python3 << 'PYTHON' + METRICS_FILE="$METRICS_FILE" python3 << 'PYTHON' import json import os @@ -103,7 +103,7 @@ with open(metrics_file, 'r') as f: if not data['operations']: print("No operations tracked yet.") - return + raise SystemExit(0) print("\n=== CURRENT METRICS ===") print(f"Repo: {data['repo']}\n") @@ -130,7 +130,7 @@ PYTHON weekly_report() { [[ ! -f "$METRICS_FILE" ]] && { echo "No metrics yet."; return; } - python3 << 'PYTHON' + METRICS_FILE="$METRICS_FILE" python3 << 'PYTHON' import json import os diff --git a/skills/python-patterns/references/testing.md b/skills/python-patterns/references/testing.md index ffe6aee..353f564 100644 --- a/skills/python-patterns/references/testing.md +++ b/skills/python-patterns/references/testing.md @@ -2,7 +2,7 @@ ## TDD Cycle -**RED** (write failing test) → **GREEN** (minimal code to pass) → **REFACTOR** (improve while green). Target 80%+ coverage. +**RED** (write failing test) → **GREEN** (minimal code to pass) → **REFACTOR** (improve while green). Follow the project's configured coverage target when one exists. ## Testing Patterns @@ -33,4 +33,4 @@ def test_model_reproducibility(sample_df): - **Test behavior, not internals** — assert outputs, not private attributes - **Independent tests** — each test sets up its own data - **Test edge cases** — None, empty DataFrame, NaN, inf -- Target **80%+ coverage** +- Follow the project's configured coverage target; otherwise prioritize meaningful behavior coverage. diff --git a/skills/security-check/SKILL.md b/skills/security-check/SKILL.md index cdb9411..ee9b85c 100644 --- a/skills/security-check/SKILL.md +++ b/skills/security-check/SKILL.md @@ -1,7 +1,7 @@ --- name: security-check version: "1.0" -description: Scan Python projects for credential leaks, secrets in code, insecure patterns, LLM API key exposure, PII leakage to external AI services, and .env/.gitignore misconfigurations. Focused on data science pipelines handling API keys, tokens, and LLM integrations. +description: Scan projects for credential leaks, secrets in code, insecure patterns, LLM API key exposure, PII leakage to external AI services, and .env/.gitignore misconfigurations. Especially useful for data and API integrations, regardless of implementation language. --- # Security Check Skill diff --git a/skills/semantic-versioning/SKILL.md b/skills/semantic-versioning/SKILL.md index d6044df..768a55a 100644 --- a/skills/semantic-versioning/SKILL.md +++ b/skills/semantic-versioning/SKILL.md @@ -6,7 +6,7 @@ description: Use when committing or pushing changes and the repository needs a v # Semantic Versioning -Determine the next version from commit history. Every pushed change gets classified; the highest-impact commit drives the bump. +Determine the next version from commit history when preparing a release. The highest-impact release-relevant commit drives the bump. ## When to Activate diff --git a/skills/verification-loop/guidelines.md b/skills/verification-loop/guidelines.md index 930eae3..9475a41 100644 --- a/skills/verification-loop/guidelines.md +++ b/skills/verification-loop/guidelines.md @@ -14,8 +14,8 @@ ## Coverage Target -- Minimum **80%** test coverage -- If coverage drops below 80%, flag it as a finding +- Use the project's configured coverage target when one exists. +- If no target is configured, report measured coverage and prioritize important untested behavior rather than enforcing a universal percentage. ## Escalation diff --git a/skills/verification-loop/skills/phases.md b/skills/verification-loop/skills/phases.md index ad23a00..5a1082d 100644 --- a/skills/verification-loop/skills/phases.md +++ b/skills/verification-loop/skills/phases.md @@ -27,7 +27,7 @@ ruff format --check . 2>&1 pytest --cov --cov-report=term-missing -q 2>&1 | tail -50 ``` -Target: 80% minimum coverage. +Use the project's configured coverage target when one exists. Otherwise report measured coverage and identify untested high-risk code without imposing a universal threshold. ## Phase 5: Code Review