kodelyth-ecc 2.18.0 → 2.19.0

package/.agent/rules/git-mastery.md

@@ -0,0 +1,366 @@
+---
+name: git-mastery
+description: Advanced Git workflows, branching strategies, history management, and team collaboration patterns. Covers trunk-based development, interactive rebase, bisect debugging, monorepo workflows, and professional commit hygiene. Powered by Kodelyth.
+origin: Kodelyth
+---
+
+# Git Mastery — Advanced Git Workflows
+
+Professional-grade Git patterns for individuals and teams. Powered by Kodelyth.
+
+## When to Use
+
+- Setting up a branching strategy for a team
+- Learning advanced Git commands (rebase, bisect, worktree)
+- Fixing a messy commit history before merging
+- Debugging when a bug was introduced using `git bisect`
+- Working in a monorepo
+- Enforcing commit message standards
+
+---
+
+## Branching Strategies
+
+### Trunk-Based Development (Recommended for most teams)
+
+```
+main (always deployable)
+ ├── feat/add-oauth      (short-lived, < 2 days)
+ ├── fix/null-check      (short-lived, < 1 day)
+ └── chore/upgrade-deps  (short-lived)
+```
+
+**Rules:**
+- All branches off `main`, all PRs back to `main`
+- Branches live < 2 days — longer = higher merge conflict risk
+- Use feature flags to ship incomplete features safely
+- Every commit to `main` is potentially deployable
+
+```bash
+# Start a feature
+git checkout main && git pull
+git checkout -b feat/user-authentication
+
+# Sync with main daily (rebase, don't merge)
+git fetch origin
+git rebase origin/main
+
+# PR → squash merge → delete branch
+```
+
+### Gitflow (For versioned software with release cycles)
+
+```
+main          (production releases only)
+develop       (integration branch)
+ ├── feature/xyz     (features off develop)
+ ├── release/1.2.0   (stabilization)
+ └── hotfix/critical (off main, merges to main + develop)
+```
+
+**Use when**: You ship versioned releases (mobile apps, libraries, enterprise software)
+**Avoid when**: You deploy continuously (web apps, SaaS)
+
+### Ship / Show / Ask (For experienced teams)
+
+```
+Ship: Commit directly to main (trivial changes, docs, chores)
+Show: Open PR, merge immediately without review (small, safe changes)
+Ask:  Open PR, wait for review (significant changes, risk)
+```
+
+---
+
+## Commit Message Mastery
+
+### Conventional Commits Format
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer]
+```
+
+**Types:**
+```
+feat:     New feature (triggers MINOR version bump)
+fix:      Bug fix (triggers PATCH version bump)
+docs:     Documentation only
+style:    Formatting (no logic change)
+refactor: Code restructure (no feature, no fix)
+test:     Adding or fixing tests
+chore:    Build, tooling, dependencies
+perf:     Performance improvement
+ci:       CI/CD changes
+revert:   Reverting a commit
+```
+
+**Examples:**
+```bash
+# Good
+git commit -m "feat(auth): add OAuth2 login with Google"
+git commit -m "fix(cart): prevent double-submission on slow networks"
+git commit -m "refactor(user): extract UserService from UserController"
+git commit -m "test(payment): add integration test for failed webhooks"
+
+# Bad
+git commit -m "fix bug"
+git commit -m "WIP"
+git commit -m "changes"
+git commit -m "asdf"
+```
+
+**With body (for significant changes):**
+```bash
+git commit -m "feat(billing): add Stripe subscription management
+
+Adds three subscription tiers: Free, Pro ($29/mo), Enterprise ($99/mo).
+Payment flow uses Stripe Checkout. Subscription status synced via webhooks.
+
+Breaking: removes legacy PayPal integration (deprecated since v1.3)
+Closes #234"
+```
+
+---
+
+## Interactive Rebase — History Surgery
+
+### Squash WIP commits before merging
+
+```bash
+# You have 5 messy commits you want to clean up
+git log --oneline -5
+# abc1234 fix
+# def5678 WIP
+# ghi9012 more changes
+# jkl3456 actually fix it
+# mno7890 feat: add user search
+
+# Squash all 5 into 1 clean commit
+git rebase -i HEAD~5
+
+# In the editor:
+# pick mno7890 feat: add user search
+# squash jkl3456 actually fix it
+# squash ghi9012 more changes
+# squash def5678 WIP
+# squash abc1234 fix
+# → writes a clean single commit message
+```
+
+### Fix a commit message (already pushed? see below)
+
+```bash
+# Fix the last commit message
+git commit --amend -m "feat(search): add full-text user search with pagination"
+
+# Fix a message 3 commits back
+git rebase -i HEAD~3
+# Change "pick" to "reword" on the target commit
+```
+
+### Fixup — add changes to a previous commit
+
+```bash
+# You forgot to add a file to a commit 2 commits ago
+git add forgotten-file.ts
+git commit --fixup HEAD~2
+
+# Then squash fixup into its target automatically
+git rebase -i --autosquash HEAD~3
+```
+
+### Split a large commit into smaller ones
+
+```bash
+git rebase -i HEAD~1
+# Change "pick" to "edit" on the commit to split
+
+# Now git stops at that commit
+git reset HEAD~1         # unstage all changes
+git add -p               # selectively stage first logical change
+git commit -m "feat: add user model"
+git add -p               # stage second logical change
+git commit -m "feat: add user repository"
+git rebase --continue    # finish the rebase
+```
+
+---
+
+## Git Bisect — Binary Search for Bugs
+
+When you know "it worked in v1.2, broke somewhere before v1.5":
+
+```bash
+git bisect start
+git bisect bad                    # current HEAD is broken
+git bisect good v1.2.0            # this tag/commit was good
+
+# Git checks out the midpoint automatically
+# Test it (run your test, check the behavior)
+git bisect good   # if this commit is OK
+git bisect bad    # if this commit has the bug
+
+# Repeat — git halves the search space each time
+# With 1000 commits, it takes at most 10 steps
+
+# Automate with a test script
+git bisect run npm test -- --grep "the failing test"
+
+# When done
+git bisect reset  # returns to original HEAD
+```
+
+---
+
+## Git Worktrees — Multiple Branches Simultaneously
+
+Work on a hotfix while keeping your feature branch untouched:
+
+```bash
+# Create a new worktree (separate directory, same repo)
+git worktree add ../hotfix-payment hotfix/payment-crash
+
+# Now you have two working directories:
+#   ~/project/           → your feature branch
+#   ~/hotfix-payment/    → the hotfix branch
+
+# Work in the hotfix directory, commit, push, PR
+cd ../hotfix-payment
+# ... make fix ...
+git commit -m "fix(payment): prevent double charge on retry"
+git push origin hotfix/payment-crash
+
+# Clean up when done
+cd ~/project
+git worktree remove ../hotfix-payment
+```
+
+---
+
+## Git Log — Find Anything in History
+
+```bash
+# See changes to a specific file over time
+git log --follow --oneline -- src/components/Auth.tsx
+
+# See who last changed each line (with commit + author)
+git blame src/components/Auth.tsx
+
+# Search commit messages
+git log --oneline --grep="payment"
+
+# Search code changes (find when a string was added or removed)
+git log -S "functionName" --oneline
+
+# See what changed between two tags
+git log v1.2.0..v1.3.0 --oneline
+
+# Visualize branch graph
+git log --oneline --graph --decorate --all
+```
+
+---
+
+## Git Stash — Save Work in Progress
+
+```bash
+# Stash everything (tracked + untracked)
+git stash push -u -m "WIP: halfway through auth refactor"
+
+# List stashes
+git stash list
+# stash@{0}: WIP: halfway through auth refactor
+# stash@{1}: quick fix attempt
+
+# Apply and remove the latest stash
+git stash pop
+
+# Apply a specific stash (keep it)
+git stash apply stash@{1}
+
+# Stash only specific files
+git stash push -m "partial" -- src/auth.ts src/user.ts
+
+# Drop a stash
+git stash drop stash@{1}
+```
+
+---
+
+## Monorepo Git Patterns
+
+```bash
+# Only run CI for changed packages
+git diff --name-only origin/main...HEAD | grep "^packages/"
+
+# Sparse checkout — only clone part of a large monorepo
+git clone --filter=blob:none --sparse https://github.com/org/monorepo
+git sparse-checkout init --cone
+git sparse-checkout set packages/my-package
+
+# Tag per package
+git tag packages/auth@1.2.0
+git tag packages/api@2.0.1
+
+# Find which package a file belongs to
+git log --oneline -- packages/billing/
+```
+
+---
+
+## Branch Protection Rules (GitHub/GitLab)
+
+```yaml
+# Recommended branch protection for main:
+required_status_checks:
+  strict: true           # must be up to date with main
+  contexts:
+    - "CI / test"
+    - "CI / lint"
+    - "CI / typecheck"
+
+required_pull_request_reviews:
+  required_approving_review_count: 1
+  dismiss_stale_reviews: true
+  require_code_owner_reviews: true
+
+restrictions:
+  push: []               # nobody can push directly to main
+  force_push: false      # never allow force push to main
+  delete: false          # never allow delete of main
+```
+
+---
+
+## Emergency Recovery
+
+```bash
+# Accidentally deleted a branch?
+git reflog                           # find the last commit hash
+git checkout -b recovered-branch <hash>
+
+# Accidentally force pushed?
+git reflog origin/main              # see the hash before the force push
+git push origin <hash>:main --force # restore it
+
+# Committed to the wrong branch?
+git log --oneline -3                # note the commit hash
+git reset HEAD~1 --soft             # undo commit, keep changes staged
+git stash                           # stash the changes
+git checkout correct-branch
+git stash pop                       # apply changes to correct branch
+git commit -m "feat: the actual message"
+
+# Accidentally committed secrets?
+# 1. Rotate the secret IMMEDIATELY (assume it's compromised)
+# 2. Remove from history:
+git filter-repo --path secrets.env --invert-paths
+# OR use BFG Repo Cleaner for simpler cases
+```
+
+---
+
+> Powered by Kodelyth — Git is not just version control, it's your project's memory.

package/.agent/rules/git-workflow.md

@@ -0,0 +1,24 @@
+# Git 工作流
+
+## 提交消息格式
+```
+<类型>: <描述>
+
+<可选正文>
+```
+
+类型：feat, fix, refactor, docs, test, chore, perf, ci
+
+注意：通过 ~/.claude/settings.json 全局禁用归属。
+
+## Pull Request 工作流
+
+创建 PR 时：
+1. 分析完整提交历史（不仅是最新提交）
+2. 使用 `git diff [base-branch]...HEAD` 查看所有更改
+3. 起草全面的 PR 摘要
+4. 包含带有 TODO 的测试计划
+5. 如果是新分支，使用 `-u` 标志推送
+
+> 对于 git 操作之前的完整开发流程（规划、TDD、代码审查），
+> 参见 [development-workflow.md](./development-workflow.md)。

package/.agent/rules/hooks.md

@@ -0,0 +1,23 @@
+---
+paths:
+  - "**/*.rb"
+  - "**/*.rake"
+---
+# Ruby Hooks
+
+> This file extends [common/hooks.md](../common/hooks.md) with Ruby specific content.
+
+## PostToolUse Hooks
+
+Configure in `~/.claude/settings.json`:
+
+- **RuboCop**: Auto-lint `.rb` files after edit
+  ```bash
+  rubocop --autocorrect <file>
+  ```
+- **Syntax check**: Run `ruby -c <file>` after editing
+
+## Warnings
+
+- Warn about `puts` / `p` statements in non-test `.rb` files (use `Rails.logger` or a logger instead)
+- Warn when `binding.pry` or `byebug` is left in edited files

package/.agent/rules/kodelyth-quickstart.md

@@ -0,0 +1,214 @@
+---
+name: kodelyth-quickstart
+description: Friendly getting-started guide — powered by Kodelyth. A plain-language introduction to Kodelyth ECC for new users. Explains what agents, skills, commands, and hooks are in simple terms, and guides you to the right tool for your task. Read this first.
+origin: Kodelyth
+---
+
+# Kodelyth Quickstart — Getting Started with Kodelyth ECC
+
+Welcome. This guide explains Kodelyth ECC (ECC) in plain language so you can start using it confidently in the first 10 minutes.
+
+> Powered by Kodelyth — making AI tooling friendly from the first interaction.
+
+## What Is This?
+
+Kodelyth ECC is a **plugin that makes Claude Code smarter**. It adds:
+
+- **Agents** — specialists you delegate tasks to (like hiring a contractor for a specific job)
+- **Skills** — domain knowledge loaded into Claude's context (like giving Claude a textbook to reference)
+- **Commands** — shortcuts to trigger common workflows (like macros)
+- **Hooks** — automatic actions that run before/after Claude does things (like background safety checks)
+
+You don't need to use all of them. Start with what solves your current problem.
+
+## The 4 Things You Need to Know
+
+### 1. Agents — Specialists for Specific Jobs
+
+Agents are like calling a specialist instead of doing it yourself. You delegate a task to an agent and it handles it end-to-end.
+
+**When to use an agent**: when you have a specific, defined task that matches an expert's domain.
+
+```
+# To use an agent, just say:
+"use code-reviewer"
+"use planner"
+"use debug-detective"
+```
+
+**Kodelyth agents added to this repo:**
+
+| Agent | What it does |
+|---|---|
+| `kodelyth-advisor` | Not sure what to use? Ask this agent — it guides you to the right tool |
+| `debug-detective` | Traces bugs to their root cause step by step — never guesses |
+| `ux-reviewer` | Reviews frontend code for UX and accessibility issues |
+
+**Other useful built-in agents:**
+
+| Agent | When to use it |
+|---|---|
+| `planner` | Before starting a complex feature |
+| `code-reviewer` | After writing or changing code |
+| `security-reviewer` | When code touches auth, payments, or user data |
+| `refactor-cleaner` | When code has grown messy |
+| `build-error-resolver` | When a build or compile is failing |
+| `tdd-guide` | When you want to write tests properly |
+| `performance-optimizer` | When something is slow |
+
+---
+
+### 2. Skills — Domain Knowledge on Demand
+
+Skills load expert knowledge into Claude's context for a specific topic. They're not agents — they don't do a task for you. They give Claude the right context to do it well.
+
+**When to use a skill**: when you're working in a specific language, framework, or domain and want Claude to follow best practices for it.
+
+```
+# To use a skill, type the skill name as a command:
+/python-patterns
+/golang-patterns
+/postgres-patterns
+/docker-patterns
+/coding-standards
+```
+
+**Kodelyth skills added to this repo:**
+
+| Skill | What it covers |
+|---|---|
+| `/kodelyth-quickstart` | This guide — plain-language intro to ECC |
+| `/smart-debug` | Systematic debugging framework for any language |
+
+**Other useful built-in skills:**
+
+| Skill | When to use it |
+|---|---|
+| `/coding-standards` | General code quality rules (naming, structure, etc.) |
+| `/python-patterns` | Python best practices |
+| `/golang-patterns` | Go best practices |
+| `/typescript-patterns` | TypeScript/React best practices |
+| `/postgres-patterns` | Database query and schema patterns |
+| `/docker-patterns` | Container and Docker Compose patterns |
+| `/security-review` | Security audit guidance |
+| `/api-design` | REST API design conventions |
+
+---
+
+### 3. Commands — Workflow Shortcuts
+
+Commands trigger multi-step workflows with a single slash command.
+
+**When to use commands**: for repeatable workflows you do often.
+
+```
+/tdd          → Start test-driven development workflow
+/plan         → Create an implementation plan
+/code-review  → Trigger a quality review
+/build-fix    → Fix a broken build
+/e2e          → Generate and run E2E tests
+/learn        → Extract reusable patterns from this session
+```
+
+---
+
+### 4. Hooks — Automatic Background Protection
+
+Hooks run automatically — you don't invoke them. They silently protect you from common mistakes.
+
+**What's running in the background right now:**
+
+| Hook | What it does |
+|---|---|
+| Session start | Loads context from your last session |
+| Pre-commit check | Catches `console.log`, secrets, and bad commit messages |
+| Quality gate | Runs type checks and formatting after you edit files |
+| Git push reminder | Prompts you to review before pushing |
+| Cost tracker | Logs token usage per session |
+| Desktop notify | Sends a macOS notification when Claude finishes a long task |
+
+You don't need to do anything — hooks are already active.
+
+---
+
+## Your First 5 Minutes — A Practical Path
+
+**Step 1: Get guidance on what to use**
+```
+use kodelyth-advisor
+```
+Tell it what you're building. It will recommend the right agents and skills.
+
+**Step 2: Load the right skill for your stack**
+```
+/python-patterns          # if you're working in Python
+/typescript-patterns      # if you're working in TypeScript/React
+/golang-patterns          # if you're working in Go
+/coding-standards         # if you want general best practices
+```
+
+**Step 3: Plan your feature before coding**
+```
+use planner
+```
+Describe what you want to build. The planner will produce a phased implementation plan.
+
+**Step 4: After you write code, review it**
+```
+use code-reviewer
+```
+This catches security issues, code quality problems, and missing tests before they become problems.
+
+**Step 5: If something breaks, debug it systematically**
+```
+use debug-detective
+/smart-debug
+```
+Tell the agent the symptom. It will trace the bug to its root cause.
+
+**Bonus: See your AI workspace at a glance**
+```
+npx kodelyth-ecc dashboard
+```
+Opens the local observability dashboard at `http://127.0.0.1:5747`. Inspect memory captures, BM25 search across past solutions, evolve proposals, the full skill and agent catalog, swarm sessions, and token-budget snapshots — all local, zero telemetry.
+
+---
+
+## Common Questions
+
+**Q: What's the difference between an agent and a skill?**
+An agent *does* something (takes actions, reads files, writes code). A skill *informs* Claude (loads reference knowledge into context). Use agents for tasks, skills for expertise.
+
+**Q: How do I know which agent to use?**
+When in doubt: `use kodelyth-advisor` — it will recommend the right one for your situation.
+
+**Q: Can I use multiple skills at once?**
+Yes. Load any combination of skills and Claude will use all of them.
+
+**Q: Do hooks cost me tokens?**
+Minimal. Most hooks are fast shell scripts that run outside Claude's context window.
+
+**Q: The command didn't do anything obvious — is it working?**
+Commands load context into the conversation. Claude will then follow the skill's guidance in its next response. Try asking a question related to the skill topic.
+
+---
+
+## Quick Reference Card
+
+```
+NOT SURE WHERE TO START?    →  use kodelyth-advisor
+PLANNING A FEATURE?         →  use planner  or  /plan
+REVIEWING CODE?             →  use code-reviewer  or  /code-review
+DEBUGGING?                  →  use debug-detective  or  /smart-debug
+SECURITY CONCERN?           →  use security-reviewer
+TESTS NEEDED?               →  use tdd-guide  or  /tdd
+BUILD BROKEN?               →  use build-error-resolver  or  /build-fix
+UX REVIEW?                  →  use ux-reviewer
+LOAD LANGUAGE PATTERNS?     →  /python-patterns, /golang-patterns, etc.
+GENERAL CODE STANDARDS?     →  /coding-standards
+OBSERVABILITY DASHBOARD?    →  npx kodelyth-ecc dashboard  (localhost:5747)
+```
+
+---
+
+> Powered by Kodelyth — you got this.