thanh-kit 2.5.0 → 2.5.2

package/templates/skills/code-review/references/verification-before-completion.md

@@ -1,139 +1,139 @@
----
-name: verification-before-completion
-description: Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
----
-
-# Verification Before Completion
-
-## Overview
-
-Claiming work is complete without verification is dishonesty, not efficiency.
-
-**Core principle:** Evidence before claims, always.
-
-**Violating the letter of this rule is violating the spirit of this rule.**
-
-## The Iron Law
-
-```
-NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
-```
-
-If you haven't run the verification command in this message, you cannot claim it passes.
-
-## The Gate Function
-
-```
-BEFORE claiming any status or expressing satisfaction:
-
-1. IDENTIFY: What command proves this claim?
-2. RUN: Execute the FULL command (fresh, complete)
-3. READ: Full output, check exit code, count failures
-4. VERIFY: Does output confirm the claim?
-   - If NO: State actual status with evidence
-   - If YES: State claim WITH evidence
-5. ONLY THEN: Make the claim
-
-Skip any step = lying, not verifying
-```
-
-## Common Failures
-
-| Claim | Requires | Not Sufficient |
-|-------|----------|----------------|
-| Tests pass | Test command output: 0 failures | Previous run, "should pass" |
-| Linter clean | Linter output: 0 errors | Partial check, extrapolation |
-| Build succeeds | Build command: exit 0 | Linter passing, logs look good |
-| Bug fixed | Test original symptom: passes | Code changed, assumed fixed |
-| Regression test works | Red-green cycle verified | Test passes once |
-| Agent completed | VCS diff shows changes | Agent reports "success" |
-| Requirements met | Line-by-line checklist | Tests passing |
-
-## Red Flags - STOP
-
-- Using "should", "probably", "seems to"
-- Expressing satisfaction before verification ("Great!", "Perfect!", "Done!", etc.)
-- About to commit/push/PR without verification
-- Trusting agent success reports
-- Relying on partial verification
-- Thinking "just this once"
-- Tired and wanting work over
-- **ANY wording implying success without having run verification**
-
-## Rationalization Prevention
-
-| Excuse | Reality |
-|--------|---------|
-| "Should work now" | RUN the verification |
-| "I'm confident" | Confidence ≠ evidence |
-| "Just this once" | No exceptions |
-| "Linter passed" | Linter ≠ compiler |
-| "Agent said success" | Verify independently |
-| "I'm tired" | Exhaustion ≠ excuse |
-| "Partial check is enough" | Partial proves nothing |
-| "Different words so rule doesn't apply" | Spirit over letter |
-
-## Key Patterns
-
-**Tests:**
-```
-✅ [Run test command] [See: 34/34 pass] "All tests pass"
-❌ "Should pass now" / "Looks correct"
-```
-
-**Regression tests (TDD Red-Green):**
-```
-✅ Write → Run (pass) → Revert fix → Run (MUST FAIL) → Restore → Run (pass)
-❌ "I've written a regression test" (without red-green verification)
-```
-
-**Build:**
-```
-✅ [Run build] [See: exit 0] "Build passes"
-❌ "Linter passed" (linter doesn't check compilation)
-```
-
-**Requirements:**
-```
-✅ Re-read plan → Create checklist → Verify each → Report gaps or completion
-❌ "Tests pass, phase complete"
-```
-
-**Agent delegation:**
-```
-✅ Agent reports success → Check VCS diff → Verify changes → Report actual state
-❌ Trust agent report
-```
-
-## Why This Matters
-
-From 24 failure memories:
-- your human partner said "I don't believe you" - trust broken
-- Undefined functions shipped - would crash
-- Missing requirements shipped - incomplete features
-- Time wasted on false completion → redirect → rework
-- Violates: "Honesty is a core value. If you lie, you'll be replaced."
-
-## When To Apply
-
-**ALWAYS before:**
-- ANY variation of success/completion claims
-- ANY expression of satisfaction
-- ANY positive statement about work state
-- Committing, PR creation, task completion
-- Moving to next task
-- Delegating to agents
-
-**Rule applies to:**
-- Exact phrases
-- Paraphrases and synonyms
-- Implications of success
-- ANY communication suggesting completion/correctness
-
-## The Bottom Line
-
-**No shortcuts for verification.**
-
-Run the command. Read the output. THEN claim the result.
-
+---
+name: verification-before-completion
+description: Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
+---
+
+# Verification Before Completion
+
+## Overview
+
+Claiming work is complete without verification is dishonesty, not efficiency.
+
+**Core principle:** Evidence before claims, always.
+
+**Violating the letter of this rule is violating the spirit of this rule.**
+
+## The Iron Law
+
+```
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+```
+
+If you haven't run the verification command in this message, you cannot claim it passes.
+
+## The Gate Function
+
+```
+BEFORE claiming any status or expressing satisfaction:
+
+1. IDENTIFY: What command proves this claim?
+2. RUN: Execute the FULL command (fresh, complete)
+3. READ: Full output, check exit code, count failures
+4. VERIFY: Does output confirm the claim?
+   - If NO: State actual status with evidence
+   - If YES: State claim WITH evidence
+5. ONLY THEN: Make the claim
+
+Skip any step = lying, not verifying
+```
+
+## Common Failures
+
+| Claim | Requires | Not Sufficient |
+|-------|----------|----------------|
+| Tests pass | Test command output: 0 failures | Previous run, "should pass" |
+| Linter clean | Linter output: 0 errors | Partial check, extrapolation |
+| Build succeeds | Build command: exit 0 | Linter passing, logs look good |
+| Bug fixed | Test original symptom: passes | Code changed, assumed fixed |
+| Regression test works | Red-green cycle verified | Test passes once |
+| Agent completed | VCS diff shows changes | Agent reports "success" |
+| Requirements met | Line-by-line checklist | Tests passing |
+
+## Red Flags - STOP
+
+- Using "should", "probably", "seems to"
+- Expressing satisfaction before verification ("Great!", "Perfect!", "Done!", etc.)
+- About to commit/push/PR without verification
+- Trusting agent success reports
+- Relying on partial verification
+- Thinking "just this once"
+- Tired and wanting work over
+- **ANY wording implying success without having run verification**
+
+## Rationalization Prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "Should work now" | RUN the verification |
+| "I'm confident" | Confidence ≠ evidence |
+| "Just this once" | No exceptions |
+| "Linter passed" | Linter ≠ compiler |
+| "Agent said success" | Verify independently |
+| "I'm tired" | Exhaustion ≠ excuse |
+| "Partial check is enough" | Partial proves nothing |
+| "Different words so rule doesn't apply" | Spirit over letter |
+
+## Key Patterns
+
+**Tests:**
+```
+✅ [Run test command] [See: 34/34 pass] "All tests pass"
+❌ "Should pass now" / "Looks correct"
+```
+
+**Regression tests (TDD Red-Green):**
+```
+✅ Write → Run (pass) → Revert fix → Run (MUST FAIL) → Restore → Run (pass)
+❌ "I've written a regression test" (without red-green verification)
+```
+
+**Build:**
+```
+✅ [Run build] [See: exit 0] "Build passes"
+❌ "Linter passed" (linter doesn't check compilation)
+```
+
+**Requirements:**
+```
+✅ Re-read plan → Create checklist → Verify each → Report gaps or completion
+❌ "Tests pass, phase complete"
+```
+
+**Agent delegation:**
+```
+✅ Agent reports success → Check VCS diff → Verify changes → Report actual state
+❌ Trust agent report
+```
+
+## Why This Matters
+
+From 24 failure memories:
+- your human partner said "I don't believe you" - trust broken
+- Undefined functions shipped - would crash
+- Missing requirements shipped - incomplete features
+- Time wasted on false completion → redirect → rework
+- Violates: "Honesty is a core value. If you lie, you'll be replaced."
+
+## When To Apply
+
+**ALWAYS before:**
+- ANY variation of success/completion claims
+- ANY expression of satisfaction
+- ANY positive statement about work state
+- Committing, PR creation, task completion
+- Moving to next task
+- Delegating to agents
+
+**Rule applies to:**
+- Exact phrases
+- Paraphrases and synonyms
+- Implications of success
+- ANY communication suggesting completion/correctness
+
+## The Bottom Line
+
+**No shortcuts for verification.**
+
+Run the command. Read the output. THEN claim the result.
+
 This is non-negotiable.

package/templates/skills/coding-level/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: ck:coding-level
+description: "Set coding experience level for tailored explanations and output format."
+argument-hint: "[0-5]"
+---
+
+# Coding Level
+
+Set your coding experience level for tailored explanations and output format.
+
+## Usage
+
+`/ck:coding-level [0-5]`
+
+## Levels
+
+| Level | Name | Description |
+|-------|------|-------------|
+| 0 | ELI5 | Zero coding experience - analogies, no jargon, step-by-step |
+| 1 | Junior | 0-2 years - concepts explained, WHY not just HOW |
+| 2 | Mid-Level | 3-5 years - design patterns, system thinking |
+| 3 | Senior | 5-8 years - trade-offs, business context, architecture |
+| 4 | Tech Lead | 8-10 years - risk assessment, business impact, strategy |
+| 5 | God Mode | Expert - default behavior, maximum efficiency (default) |
+
+## How It Works
+
+1. Set `codingLevel` in `.claude/.ck.json`
+2. Guidelines are **automatically injected** on every session start
+3. No manual activation needed - it just works!
+
+## Example
+
+Set level 1 in `.claude/.ck.json`:
+```json
+{
+  "codingLevel": 1,
+  ...
+}
+```
+
+Next session, Claude will automatically:
+- Explain concepts and techniques clearly
+- Always explain WHY, not just HOW
+- Point out common mistakes
+- Add "Key Takeaways" after implementations
+
+## Optional: Manual Output Styles
+
+For finer control, you can also use `/output-style` with these styles:
+- `coding-level-0-eli5`
+- `coding-level-1-junior`
+- `coding-level-2-mid`
+- `coding-level-3-senior`
+- `coding-level-4-lead`
+- `coding-level-5-god`

package/templates/skills/common/README.md

@@ -0,0 +1,120 @@
+# Common Skill Utilities
+
+This directory contains shared utilities used across multiple skills.
+
+## API Key Helper
+
+`api_key_helper.py` provides standardized configuration for all Gemini-based skills, supporting both Google AI Studio and Vertex AI endpoints.
+
+### Usage in Skills
+
+```python
+import sys
+from pathlib import Path
+
+# Add common directory to path
+common_dir = Path(__file__).parent.parent.parent / 'common'
+sys.path.insert(0, str(common_dir))
+
+from api_key_helper import get_api_key_or_exit
+
+# Get API key with automatic error handling
+api_key = get_api_key_or_exit()
+```
+
+### API Key Lookup Order
+
+The helper checks for `GEMINI_API_KEY` in this order:
+
+1. **Process environment variable** (recommended for development)
+   ```bash
+   export GEMINI_API_KEY='your-api-key'
+   ```
+
+2. **Project root `.env` file**
+   ```bash
+   echo 'GEMINI_API_KEY=your-api-key' > .env
+   ```
+
+3. **.claude/.env file**
+   ```bash
+   echo 'GEMINI_API_KEY=your-api-key' > .claude/.env
+   ```
+
+4. **.claude/skills/.env file** (shared across all Gemini skills)
+   ```bash
+   echo 'GEMINI_API_KEY=your-api-key' > .claude/skills/.env
+   ```
+
+5. **Skill directory `.env` file**
+   ```bash
+   echo 'GEMINI_API_KEY=your-api-key' > .claude/skills/your-skill/.env
+   ```
+
+### Vertex AI Support
+
+To use Vertex AI instead of Google AI Studio:
+
+```bash
+# Enable Vertex AI
+export GEMINI_USE_VERTEX=true
+export VERTEX_PROJECT_ID=your-gcp-project-id
+export VERTEX_LOCATION=us-central1  # Optional, defaults to us-central1
+```
+
+Or in `.env` file:
+```
+GEMINI_USE_VERTEX=true
+VERTEX_PROJECT_ID=your-gcp-project-id
+VERTEX_LOCATION=us-central1
+```
+
+### Using get_client() Helper
+
+For automatic client selection (AI Studio or Vertex AI):
+
+```python
+from api_key_helper import get_client
+
+# Get appropriate client based on configuration
+client_info = get_client()
+
+if client_info['type'] == 'vertex':
+    # Using Vertex AI
+    from vertexai.generative_models import GenerativeModel
+    model = GenerativeModel('gemini-2.5-flash')
+    response = model.generate_content("Hello")
+else:
+    # Using AI Studio
+    client = client_info['client']
+    response = client.models.generate_content(
+        model='gemini-2.5-flash',
+        contents="Hello"
+    )
+```
+
+### Using get_vertex_config() Helper
+
+For checking Vertex AI configuration:
+
+```python
+from api_key_helper import get_vertex_config
+
+vertex_config = get_vertex_config()
+if vertex_config['use_vertex']:
+    print(f"Using Vertex AI")
+    print(f"Project: {vertex_config['project_id']}")
+    print(f"Location: {vertex_config['location']}")
+```
+
+### Error Handling
+
+If the API key is not found, the helper will:
+- Print a clear error message
+- Show all available methods to set the API key
+- Provide the URL to obtain an API key
+- Exit with status code 1
+
+For Vertex AI, if `VERTEX_PROJECT_ID` is missing when `GEMINI_USE_VERTEX=true`, the helper will provide clear instructions.
+
+This ensures users get immediate, actionable feedback when configuration is missing.