kodelyth-ecc 2.18.0 → 2.19.0

package/.aider-ecc/commands/python-review.md

@@ -0,0 +1,297 @@
+---
+description: Comprehensive Python code review for PEP 8 compliance, type hints, security, and Pythonic idioms. Invokes the python-reviewer agent.
+---
+
+# Python Code Review
+
+This command invokes the **python-reviewer** agent for comprehensive Python-specific code review.
+
+## What This Command Does
+
+1. **Identify Python Changes**: Find modified `.py` files via `git diff`
+2. **Run Static Analysis**: Execute `ruff`, `mypy`, `pylint`, `black --check`
+3. **Security Scan**: Check for SQL injection, command injection, unsafe deserialization
+4. **Type Safety Review**: Analyze type hints and mypy errors
+5. **Pythonic Code Check**: Verify code follows PEP 8 and Python best practices
+6. **Generate Report**: Categorize issues by severity
+
+## When to Use
+
+Use `/python-review` when:
+- After writing or modifying Python code
+- Before committing Python changes
+- Reviewing pull requests with Python code
+- Onboarding to a new Python codebase
+- Learning Pythonic patterns and idioms
+
+## Review Categories
+
+### CRITICAL (Must Fix)
+- SQL/Command injection vulnerabilities
+- Unsafe eval/exec usage
+- Pickle unsafe deserialization
+- Hardcoded credentials
+- YAML unsafe load
+- Bare except clauses hiding errors
+
+### HIGH (Should Fix)
+- Missing type hints on public functions
+- Mutable default arguments
+- Swallowing exceptions silently
+- Not using context managers for resources
+- C-style looping instead of comprehensions
+- Using type() instead of isinstance()
+- Race conditions without locks
+
+### MEDIUM (Consider)
+- PEP 8 formatting violations
+- Missing docstrings on public functions
+- Print statements instead of logging
+- Inefficient string operations
+- Magic numbers without named constants
+- Not using f-strings for formatting
+- Unnecessary list creation
+
+## Automated Checks Run
+
+```bash
+# Type checking
+mypy .
+
+# Linting and formatting
+ruff check .
+black --check .
+isort --check-only .
+
+# Security scanning
+bandit -r .
+
+# Dependency audit
+pip-audit
+safety check
+
+# Testing
+pytest --cov=app --cov-report=term-missing
+```
+
+## Example Usage
+
+```text
+User: /python-review
+
+Agent:
+# Python Code Review Report
+
+## Files Reviewed
+- app/routes/user.py (modified)
+- app/services/auth.py (modified)
+
+## Static Analysis Results
+✓ ruff: No issues
+✓ mypy: No errors
+WARNING: black: 2 files need reformatting
+✓ bandit: No security issues
+
+## Issues Found
+
+[CRITICAL] SQL Injection vulnerability
+File: app/routes/user.py:42
+Issue: User input directly interpolated into SQL query
+```python
+query = f"SELECT * FROM users WHERE id = {user_id}"  # Bad
+```
+Fix: Use parameterized query
+```python
+query = "SELECT * FROM users WHERE id = %s"  # Good
+cursor.execute(query, (user_id,))
+```
+
+[HIGH] Mutable default argument
+File: app/services/auth.py:18
+Issue: Mutable default argument causes shared state
+```python
+def process_items(items=[]):  # Bad
+    items.append("new")
+    return items
+```
+Fix: Use None as default
+```python
+def process_items(items=None):  # Good
+    if items is None:
+        items = []
+    items.append("new")
+    return items
+```
+
+[MEDIUM] Missing type hints
+File: app/services/auth.py:25
+Issue: Public function without type annotations
+```python
+def get_user(user_id):  # Bad
+    return db.find(user_id)
+```
+Fix: Add type hints
+```python
+def get_user(user_id: str) -> Optional[User]:  # Good
+    return db.find(user_id)
+```
+
+[MEDIUM] Not using context manager
+File: app/routes/user.py:55
+Issue: File not closed on exception
+```python
+f = open("config.json")  # Bad
+data = f.read()
+f.close()
+```
+Fix: Use context manager
+```python
+with open("config.json") as f:  # Good
+    data = f.read()
+```
+
+## Summary
+- CRITICAL: 1
+- HIGH: 1
+- MEDIUM: 2
+
+Recommendation: FAIL: Block merge until CRITICAL issue is fixed
+
+## Formatting Required
+Run: `black app/routes/user.py app/services/auth.py`
+```
+
+## Approval Criteria
+
+| Status | Condition |
+|--------|-----------|
+| PASS: Approve | No CRITICAL or HIGH issues |
+| WARNING: Warning | Only MEDIUM issues (merge with caution) |
+| FAIL: Block | CRITICAL or HIGH issues found |
+
+## Integration with Other Commands
+
+- Use `/tdd` first to ensure tests pass
+- Use `/code-review` for non-Python specific concerns
+- Use `/python-review` before committing
+- Use `/build-fix` if static analysis tools fail
+
+## Framework-Specific Reviews
+
+### Django Projects
+The reviewer checks for:
+- N+1 query issues (use `select_related` and `prefetch_related`)
+- Missing migrations for model changes
+- Raw SQL usage when ORM could work
+- Missing `transaction.atomic()` for multi-step operations
+
+### FastAPI Projects
+The reviewer checks for:
+- CORS misconfiguration
+- Pydantic models for request validation
+- Response models correctness
+- Proper async/await usage
+- Dependency injection patterns
+
+### Flask Projects
+The reviewer checks for:
+- Context management (app context, request context)
+- Proper error handling
+- Blueprint organization
+- Configuration management
+
+## Related
+
+- Agent: `agents/python-reviewer.md`
+- Skills: `skills/python-patterns/`, `skills/python-testing/`
+
+## Common Fixes
+
+### Add Type Hints
+```python
+# Before
+def calculate(x, y):
+    return x + y
+
+# After
+from typing import Union
+
+def calculate(x: Union[int, float], y: Union[int, float]) -> Union[int, float]:
+    return x + y
+```
+
+### Use Context Managers
+```python
+# Before
+f = open("file.txt")
+data = f.read()
+f.close()
+
+# After
+with open("file.txt") as f:
+    data = f.read()
+```
+
+### Use List Comprehensions
+```python
+# Before
+result = []
+for item in items:
+    if item.active:
+        result.append(item.name)
+
+# After
+result = [item.name for item in items if item.active]
+```
+
+### Fix Mutable Defaults
+```python
+# Before
+def append(value, items=[]):
+    items.append(value)
+    return items
+
+# After
+def append(value, items=None):
+    if items is None:
+        items = []
+    items.append(value)
+    return items
+```
+
+### Use f-strings (Python 3.6+)
+```python
+# Before
+name = "Alice"
+greeting = "Hello, " + name + "!"
+greeting2 = "Hello, {}".format(name)
+
+# After
+greeting = f"Hello, {name}!"
+```
+
+### Fix String Concatenation in Loops
+```python
+# Before
+result = ""
+for item in items:
+    result += str(item)
+
+# After
+result = "".join(str(item) for item in items)
+```
+
+## Python Version Compatibility
+
+The reviewer notes when code uses features from newer Python versions:
+
+| Feature | Minimum Python |
+|---------|----------------|
+| Type hints | 3.5+ |
+| f-strings | 3.6+ |
+| Walrus operator (`:=`) | 3.8+ |
+| Position-only parameters | 3.8+ |
+| Match statements | 3.10+ |
+| Type unions (`x | None`) | 3.10+ |
+
+Ensure your project's `pyproject.toml` or `setup.py` specifies the correct minimum Python version.

package/.aider-ecc/commands/quality-gate.md

@@ -0,0 +1,33 @@
+---
+description: Run the full quality gate — build, lint, types, tests, security scan
+---
+
+# Quality Gate Command
+
+Run the ECC quality pipeline on demand for a file or project scope.
+
+## Usage
+
+`/quality-gate [path|.] [--fix] [--strict]`
+
+- default target: current directory (`.`)
+- `--fix`: allow auto-format/fix where configured
+- `--strict`: fail on warnings where supported
+
+## Pipeline
+
+1. Detect language/tooling for target.
+2. Run formatter checks.
+3. Run lint/type checks when available.
+4. Produce a concise remediation list.
+
+## Notes
+
+This command mirrors hook behavior but is operator-invoked.
+
+## Arguments
+
+$ARGUMENTS:
+- `[path|.]` optional target path
+- `--fix` optional
+- `--strict` optional

package/.aider-ecc/commands/refactor-clean.md

@@ -0,0 +1,84 @@
+---
+description: Remove dead code, duplicates, and tech debt with safe automated cleanup
+---
+
+# Refactor Clean
+
+Safely identify and remove dead code with test verification at every step.
+
+## Step 1: Detect Dead Code
+
+Run analysis tools based on project type:
+
+| Tool | What It Finds | Command |
+|------|--------------|---------|
+| knip | Unused exports, files, dependencies | `npx knip` |
+| depcheck | Unused npm dependencies | `npx depcheck` |
+| ts-prune | Unused TypeScript exports | `npx ts-prune` |
+| vulture | Unused Python code | `vulture src/` |
+| deadcode | Unused Go code | `deadcode ./...` |
+| cargo-udeps | Unused Rust dependencies | `cargo +nightly udeps` |
+
+If no tool is available, use Grep to find exports with zero imports:
+```
+# Find exports, then check if they're imported anywhere
+```
+
+## Step 2: Categorize Findings
+
+Sort findings into safety tiers:
+
+| Tier | Examples | Action |
+|------|----------|--------|
+| **SAFE** | Unused utilities, test helpers, internal functions | Delete with confidence |
+| **CAUTION** | Components, API routes, middleware | Verify no dynamic imports or external consumers |
+| **DANGER** | Config files, entry points, type definitions | Investigate before touching |
+
+## Step 3: Safe Deletion Loop
+
+For each SAFE item:
+
+1. **Run full test suite** — Establish baseline (all green)
+2. **Delete the dead code** — Use Edit tool for surgical removal
+3. **Re-run test suite** — Verify nothing broke
+4. **If tests fail** — Immediately revert with `git checkout -- <file>` and skip this item
+5. **If tests pass** — Move to next item
+
+## Step 4: Handle CAUTION Items
+
+Before deleting CAUTION items:
+- Search for dynamic imports: `import()`, `require()`, `__import__`
+- Search for string references: route names, component names in configs
+- Check if exported from a public package API
+- Verify no external consumers (check dependents if published)
+
+## Step 5: Consolidate Duplicates
+
+After removing dead code, look for:
+- Near-duplicate functions (>80% similar) — merge into one
+- Redundant type definitions — consolidate
+- Wrapper functions that add no value — inline them
+- Re-exports that serve no purpose — remove indirection
+
+## Step 6: Summary
+
+Report results:
+
+```
+Dead Code Cleanup
+──────────────────────────────
+Deleted:   12 unused functions
+           3 unused files
+           5 unused dependencies
+Skipped:   2 items (tests failed)
+Saved:     ~450 lines removed
+──────────────────────────────
+All tests passing PASS:
+```
+
+## Rules
+
+- **Never delete without running tests first**
+- **One deletion at a time** — Atomic changes make rollback easy
+- **Skip if uncertain** — Better to keep dead code than break production
+- **Don't refactor while cleaning** — Separate concerns (clean first, refactor later)

package/.aider-ecc/commands/refactor-sprint.md

@@ -0,0 +1,77 @@
+---
+description: Parallel refactor sprint — fires refactor-cleaner + code-simplifier + type-design-analyzer + tdd-guide simultaneously. Full cleanup in one pass.
+---
+
+# /refactor-sprint — Parallel Refactor Sprint
+
+Four agents clean, simplify, type-harden, and test-cover your code simultaneously. What would take a full day of careful manual work is scoped and planned in 15 minutes.
+
+## What Gets Launched in Parallel
+
+| Agent | Focus |
+|---|---|
+| `refactor-cleaner` | Dead code, unused imports, duplicate logic, copy-paste debt, tech debt |
+| `code-simplifier` | Complex functions, deep nesting, clever one-liners, readability improvements |
+| `type-design-analyzer` | `any` types, weak discriminated unions, missing type guards, type safety gaps |
+| `tdd-guide` | Test coverage gaps, missing unit tests, untested edge cases, coverage below 80% |
+
+## Usage
+
+```
+/refactor-sprint                     # full repo
+/refactor-sprint src/auth/           # focus on a module
+/refactor-sprint --types-only        # skip cleanup, focus on type safety
+/refactor-sprint --tests-only        # skip cleanup, focus on test coverage
+```
+
+## Report Format
+
+```
+## REFACTOR SPRINT REPORT
+
+### Dead Code & Debt (refactor-cleaner)
+REMOVE:    [files, functions, imports to delete]
+EXTRACT:   [duplicated logic to consolidate]
+DEBT:      [tech debt items ranked by impact]
+
+### Simplification (code-simplifier)
+COMPLEX:   [functions that need splitting]
+NESTING:   [deep nesting to flatten with early returns]
+READABILITY: [naming and clarity improvements]
+
+### Type Safety (type-design-analyzer)
+ANY_USAGE: [locations using any/unknown unsafely]
+WEAK_TYPES:[discriminated unions to strengthen]
+GUARDS:    [missing type guards]
+
+### Test Coverage (tdd-guide)
+UNCOVERED: [critical paths with no tests]
+GAPS:      [edge cases missing]
+PLAN:      [test writing priority order]
+
+---
+TOTAL DEBT: X items | QUICK WINS: Y items
+RECOMMENDED ORDER: [prioritized action list]
+```
+
+## When to Use
+
+- Before a major feature addition (clean house first)
+- After a fast-moving sprint that accumulated debt
+- Monthly code health pass
+- Before onboarding a new team member
+- When coverage has dropped below 80%
+
+## Execute Now
+
+Invoking this command is confirmation to proceed. Execute immediately:
+
+1. Determine scope from `$ARGUMENTS`. Default: entire current project.
+2. Spawn all agents simultaneously with `run_in_background: true`:
+   - `refactor-cleaner` — dead code and duplicate logic audit
+   - `code-simplifier` — complexity and readability analysis
+   - `type-design-analyzer` — type safety audit
+   - `tdd-guide` — test coverage gap analysis
+3. Wait for all to complete.
+4. Aggregate into the Refactor Sprint Report above with a prioritized action list.
+5. End with: "Which area do you want to tackle first?"

package/.aider-ecc/commands/replay.md

@@ -0,0 +1,61 @@
+---
+description: Replay a finished swarm session — same task, optional A/B variations (different harness, agents, base ref).
+argument-hint: "[bundle.json|session-name] [--harness h] [--agents a,b] [--base-ref ref] [--execute]"
+---
+
+# /replay
+
+Re-run a completed swarm session for regression testing, A/B comparison, or post-mortem analysis.
+
+## Quick examples
+
+```
+/replay swarm-2026-05-10-4a
+/replay oauth-audit.bundle.json --execute
+/replay swarm-2026-05-10-4a --harness codex --execute
+/replay oauth-audit.bundle.json --agents security-reviewer,supply-chain-auditor --execute
+/replay swarm-baseline --base-ref refactor-branch --execute
+```
+
+## Behavior
+
+By default, prints the dry-run plan. Add `--execute` to actually create worktrees, spawn the tmux session, and launch agents. The replay session is auto-named `<original>-replay-<n>` so it never collides with the source.
+
+| Flag | Effect |
+|---|---|
+| `<target>` | Required. Either a bundle file path (`*.json`) or a session name in `.orchestration/`. |
+| `--harness <h>` | Override the launcher harness (claude / codex / opencode / windsurf / echo). |
+| `--agents a,b,c` | Replace the original agent list. |
+| `--base-ref <ref>` | Branch base for replay worktrees (default: from bundle.meta or HEAD). |
+| `--session <name>` | Override the auto-generated `-replay-N` suffix. |
+| `--replace` | Tear down any existing session/worktrees with the same names. |
+| `--execute` | Spawn worktrees + tmux + launch agents. |
+| `--write-only` | Just materialize coordination files. |
+| `--json` | Print the full plan + planConfig as JSON. |
+
+## Use cases
+
+- **Regression test prompts** — capture a baseline, replay after agent rev, compare handoffs.
+- **Reproducible bug reports** — bundle a buggy session, ship to maintainers, they can `replay --execute` locally.
+- **Model A/B test** — same task, two harnesses, side-by-side handoff diff.
+- **Re-test against new code** — `--base-ref refactor-branch` re-runs the same audit on the new code.
+- **Post-mortem** — replay an incident response swarm with new agents to see what they would have caught.
+
+## Companion commands
+
+- `/session-export <name>` — export a coordination dir as a bundle JSON.
+- `/session-import <bundle>` — restore a bundle into `.orchestration/`.
+
+## Hard rules
+
+- Never `--execute` without dry-running first.
+- Bundles are public artifacts — strip secrets before sharing externally.
+- A/B comparisons require human review; never auto-pick winners.
+
+## Implementation
+
+- Skill: `session-replay`
+- Bundle library: `scripts/replay/bundle.js`
+- Replay engine: `scripts/replay/replay.js`
+- CLI: `npx kodelyth-ecc replay`
+- Full docs: `docs/replay.md`

package/.aider-ecc/commands/resume-session.md

@@ -0,0 +1,156 @@
+---
+description: Load the most recent session file from ~/.claude/session-data/ and resume work with full context from where the last session ended.
+---
+
+# Resume Session Command
+
+Load the last saved session state and orient fully before doing any work.
+This command is the counterpart to `/save-session`.
+
+## When to Use
+
+- Starting a new session to continue work from a previous day
+- After starting a fresh session due to context limits
+- When handing off a session file from another source (just provide the file path)
+- Any time you have a session file and want Claude to fully absorb it before proceeding
+
+## Usage
+
+```
+/resume-session                                                      # loads most recent file in ~/.claude/session-data/
+/resume-session 2024-01-15                                           # loads most recent session for that date
+/resume-session ~/.claude/session-data/2024-01-15-abc123de-session.tmp  # loads a current short-id session file
+/resume-session ~/.claude/sessions/2024-01-15-session.tmp               # loads a specific legacy-format file
+```
+
+## Process
+
+### Step 1: Find the session file
+
+If no argument provided:
+
+1. Check `~/.claude/session-data/`
+2. Pick the most recently modified `*-session.tmp` file
+3. If the folder does not exist or has no matching files, tell the user:
+   ```
+   No session files found in ~/.claude/session-data/
+   Run /save-session at the end of a session to create one.
+   ```
+   Then stop.
+
+If an argument is provided:
+
+- If it looks like a date (`YYYY-MM-DD`), search `~/.claude/session-data/` first, then the legacy
+  `~/.claude/sessions/`, for files matching `YYYY-MM-DD-session.tmp` (legacy format) or
+  `YYYY-MM-DD-<shortid>-session.tmp` (current format)
+  and load the most recently modified variant for that date
+- If it looks like a file path, read that file directly
+- If not found, report clearly and stop
+
+### Step 2: Read the entire session file
+
+Read the complete file. Do not summarize yet.
+
+### Step 3: Confirm understanding
+
+Respond with a structured briefing in this exact format:
+
+```
+SESSION LOADED: [actual resolved path to the file]
+════════════════════════════════════════════════
+
+PROJECT: [project name / topic from file]
+
+WHAT WE'RE BUILDING:
+[2-3 sentence summary in your own words]
+
+CURRENT STATE:
+PASS: Working: [count] items confirmed
+ In Progress: [list files that are in progress]
+ Not Started: [list planned but untouched]
+
+WHAT NOT TO RETRY:
+[list every failed approach with its reason — this is critical]
+
+OPEN QUESTIONS / BLOCKERS:
+[list any blockers or unanswered questions]
+
+NEXT STEP:
+[exact next step if defined in the file]
+[if not defined: "No next step defined — recommend reviewing 'What Has NOT Been Tried Yet' together before starting"]
+
+════════════════════════════════════════════════
+Ready to continue. What would you like to do?
+```
+
+### Step 4: Wait for the user
+
+Do NOT start working automatically. Do NOT touch any files. Wait for the user to say what to do next.
+
+If the next step is clearly defined in the session file and the user says "continue" or "yes" or similar — proceed with that exact next step.
+
+If no next step is defined — ask the user where to start, and optionally suggest an approach from the "What Has NOT Been Tried Yet" section.
+
+---
+
+## Edge Cases
+
+**Multiple sessions for the same date** (`2024-01-15-session.tmp`, `2024-01-15-abc123de-session.tmp`):
+Load the most recently modified matching file for that date, regardless of whether it uses the legacy no-id format or the current short-id format.
+
+**Session file references files that no longer exist:**
+Note this during the briefing — "WARNING: `path/to/file.ts` referenced in session but not found on disk."
+
+**Session file is from more than 7 days ago:**
+Note the gap — "WARNING: This session is from N days ago (threshold: 7 days). Things may have changed." — then proceed normally.
+
+**User provides a file path directly (e.g., forwarded from a teammate):**
+Read it and follow the same briefing process — the format is the same regardless of source.
+
+**Session file is empty or malformed:**
+Report: "Session file found but appears empty or unreadable. You may need to create a new one with /save-session."
+
+---
+
+## Example Output
+
+```
+SESSION LOADED: /Users/you/.claude/session-data/2024-01-15-abc123de-session.tmp
+════════════════════════════════════════════════
+
+PROJECT: my-app — JWT Authentication
+
+WHAT WE'RE BUILDING:
+User authentication with JWT tokens stored in httpOnly cookies.
+Register and login endpoints are partially done. Route protection
+via middleware hasn't been started yet.
+
+CURRENT STATE:
+PASS: Working: 3 items (register endpoint, JWT generation, password hashing)
+ In Progress: app/api/auth/login/route.ts (token works, cookie not set yet)
+ Not Started: middleware.ts, app/login/page.tsx
+
+WHAT NOT TO RETRY:
+FAIL: Next-Auth — conflicts with custom Prisma adapter, threw adapter error on every request
+FAIL: localStorage for JWT — causes SSR hydration mismatch, incompatible with Next.js
+
+OPEN QUESTIONS / BLOCKERS:
+- Does cookies().set() work inside a Route Handler or only Server Actions?
+
+NEXT STEP:
+In app/api/auth/login/route.ts — set the JWT as an httpOnly cookie using
+cookies().set('token', jwt, { httpOnly: true, secure: true, sameSite: 'strict' })
+then test with Postman for a Set-Cookie header in the response.
+
+════════════════════════════════════════════════
+Ready to continue. What would you like to do?
+```
+
+---
+
+## Notes
+
+- Never modify the session file when loading it — it's a read-only historical record
+- The briefing format is fixed — do not skip sections even if they are empty
+- "What Not To Retry" must always be shown, even if it just says "None" — it's too important to miss
+- After resuming, the user may want to run `/save-session` again at the end of the new session to create a new dated file