kodelyth-ecc 2.18.0 → 2.19.0

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

@@ -0,0 +1,164 @@
+---
+description: Answer a quick side question without interrupting or losing context from the current task. Resume work automatically after answering.
+---
+
+# Aside Command
+
+Ask a question mid-task and get an immediate, focused answer — then continue right where you left off. The current task, files, and context are never modified.
+
+## When to Use
+
+- You're curious about something while Claude is working and don't want to lose momentum
+- You need a quick explanation of code Claude is currently editing
+- You want a second opinion or clarification on a decision without derailing the task
+- You need to understand an error, concept, or pattern before Claude proceeds
+- You want to ask something unrelated to the current task without starting a new session
+
+## Usage
+
+```
+/aside <your question>
+/aside what does this function actually return?
+/aside is this pattern thread-safe?
+/aside why are we using X instead of Y here?
+/aside what's the difference between foo() and bar()?
+/aside should we be worried about the N+1 query we just added?
+```
+
+## Process
+
+### Step 1: Freeze the current task state
+
+Before answering anything, mentally note:
+- What is the active task? (what file, feature, or problem was being worked on)
+- What step was in progress at the moment `/aside` was invoked?
+- What was about to happen next?
+
+Do NOT touch, edit, create, or delete any files during the aside.
+
+### Step 2: Answer the question directly
+
+Answer the question in the most concise form that is still complete and useful.
+
+- Lead with the answer, not the reasoning
+- Keep it short — if a full explanation is needed, offer to go deeper after the task
+- If the question is about the current file or code being worked on, reference it precisely (file path and line number if relevant)
+- If answering requires reading a file, read it — but read only, never write
+
+Format the response as:
+
+```
+ASIDE: [restate the question briefly]
+
+[Your answer here]
+
+— Back to task: [one-line description of what was being done]
+```
+
+### Step 3: Resume the main task
+
+After delivering the answer, immediately continue the active task from the exact point it was paused. Do not ask for permission to resume unless the aside answer revealed a blocker or a reason to reconsider the current approach (see Edge Cases).
+
+---
+
+## Edge Cases
+
+**No question provided (`/aside` with nothing after it):**
+Respond:
+```
+ASIDE: no question provided
+
+What would you like to know? (ask your question and I'll answer without losing the current task context)
+
+— Back to task: [one-line description of what was being done]
+```
+
+**Question reveals a potential problem with the current task:**
+Flag it clearly before resuming:
+```
+ASIDE: [answer]
+
+WARNING: Note: This answer suggests [issue] with the current approach. Want to address this before continuing, or proceed as planned?
+```
+Wait for the user's decision before resuming.
+
+**Question is actually a task redirect (not a side question):**
+If the question implies changing what is being built (e.g., `/aside actually, let's use Redis instead`), clarify:
+```
+ASIDE: That sounds like a direction change, not just a side question.
+Do you want to:
+  (a) Answer this as information only and keep the current plan
+  (b) Pause the current task and change approach
+```
+Wait for the user's answer — do not make assumptions.
+
+**Question is about the currently open file or code:**
+Answer from the live context. If the file was read earlier in the session, reference it directly. If not, read it now (read-only) and answer with a file:line reference.
+
+**No active task (nothing in progress when `/aside` is invoked):**
+Still use the standard wrapper so the response shape stays consistent:
+```
+ASIDE: [restate the question briefly]
+
+[Your answer here]
+
+— Back to task: no active task to resume
+```
+
+**Question requires a long answer:**
+Give the essential answer concisely, then offer:
+```
+That's the short version. Want a deeper explanation after we finish [current task]?
+```
+
+**Multiple `/aside` questions in a row:**
+Answer each one in sequence. After the last answer, resume the main task. Do not lose task state across a chain of asides.
+
+**Aside answer implies a code change is needed:**
+Note the change needed but do not make it during the aside:
+```
+ASIDE: [answer]
+
+ Worth fixing: [what should be changed]. I'll flag this after the current task unless you want to address it now.
+```
+
+**Question is ambiguous or too vague:**
+Ask one clarifying question — the shortest question that gets the information needed to answer. Do not ask multiple questions.
+
+---
+
+## Example Output
+
+```
+User: /aside what does fetchWithRetry() actually do?
+
+ASIDE: what does fetchWithRetry() do?
+
+fetchWithRetry() (src/api/retry.ts:12) attempts the request up to 3 times with
+exponential backoff (250ms → 500ms → 1s). It only retries on 5xx responses and
+network errors — 4xx errors are treated as final and not retried.
+
+— Back to task: refactoring the auth middleware in src/middleware/auth.ts
+```
+
+```
+User: /aside is the approach we're taking thread-safe?
+
+ASIDE: is the current approach thread-safe?
+
+No — the shared cache object in src/cache/store.ts:34 is mutated without locking.
+Under concurrent requests this is a race condition. It's low risk in a single-process
+Node.js server but would be a real problem with worker threads or clustering.
+
+WARNING: Note: This could affect the feature we're building. Want to address this now or continue and fix it in a follow-up?
+```
+
+---
+
+## Notes
+
+- Never modify files during an aside — read-only access only
+- The aside is a conversation pause, not a new task — the original task must always resume
+- Keep answers focused: the goal is to unblock the user quickly, not to deliver a lecture
+- If an aside sparks a larger discussion, finish the current task first unless the aside reveals a blocker
+- Asides are not saved to session files unless explicitly relevant to the task outcome

package/.aider-ecc/commands/build-fix.md

@@ -0,0 +1,66 @@
+---
+description: Incrementally fix build and type errors with minimal, safe changes
+---
+
+# Build and Fix
+
+Incrementally fix build and type errors with minimal, safe changes.
+
+## Step 1: Detect Build System
+
+Identify the project's build tool and run the build:
+
+| Indicator | Build Command |
+|-----------|---------------|
+| `package.json` with `build` script | `npm run build` or `pnpm build` |
+| `tsconfig.json` (TypeScript only) | `npx tsc --noEmit` |
+| `Cargo.toml` | `cargo build 2>&1` |
+| `pom.xml` | `mvn compile` |
+| `build.gradle` | `./gradlew compileJava` |
+| `go.mod` | `go build ./...` |
+| `pyproject.toml` | `python -m compileall -q .` or `mypy .` |
+
+## Step 2: Parse and Group Errors
+
+1. Run the build command and capture stderr
+2. Group errors by file path
+3. Sort by dependency order (fix imports/types before logic errors)
+4. Count total errors for progress tracking
+
+## Step 3: Fix Loop (One Error at a Time)
+
+For each error:
+
+1. **Read the file** — Use Read tool to see error context (10 lines around the error)
+2. **Diagnose** — Identify root cause (missing import, wrong type, syntax error)
+3. **Fix minimally** — Use Edit tool for the smallest change that resolves the error
+4. **Re-run build** — Verify the error is gone and no new errors introduced
+5. **Move to next** — Continue with remaining errors
+
+## Step 4: Guardrails
+
+Stop and ask the user if:
+- A fix introduces **more errors than it resolves**
+- The **same error persists after 3 attempts** (likely a deeper issue)
+- The fix requires **architectural changes** (not just a build fix)
+- Build errors stem from **missing dependencies** (need `npm install`, `cargo add`, etc.)
+
+## Step 5: Summary
+
+Show results:
+- Errors fixed (with file paths)
+- Errors remaining (if any)
+- New errors introduced (should be zero)
+- Suggested next steps for unresolved issues
+
+## Recovery Strategies
+
+| Situation | Action |
+|-----------|--------|
+| Missing module/import | Check if package is installed; suggest install command |
+| Type mismatch | Read both type definitions; fix the narrower type |
+| Circular dependency | Identify cycle with import graph; suggest extraction |
+| Version conflict | Check `package.json` / `Cargo.toml` for version constraints |
+| Build tool misconfiguration | Read config file; compare with working defaults |
+
+Fix one error at a time for safety. Prefer minimal diffs over refactoring.

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

@@ -0,0 +1,79 @@
+---
+description: Save a git checkpoint commit of the current working state
+argument-hint: "[message]"
+---
+
+# Checkpoint Command
+
+Create or verify a checkpoint in your workflow.
+
+## Usage
+
+`/checkpoint [create|verify|list] [name]`
+
+## Create Checkpoint
+
+When creating a checkpoint:
+
+1. Run `/verify quick` to ensure current state is clean
+2. Create a git stash or commit with checkpoint name
+3. Log checkpoint to `.claude/checkpoints.log`:
+
+```bash
+echo "$(date +%Y-%m-%d-%H:%M) | $CHECKPOINT_NAME | $(git rev-parse --short HEAD)" >> .claude/checkpoints.log
+```
+
+4. Report checkpoint created
+
+## Verify Checkpoint
+
+When verifying against a checkpoint:
+
+1. Read checkpoint from log
+2. Compare current state to checkpoint:
+   - Files added since checkpoint
+   - Files modified since checkpoint
+   - Test pass rate now vs then
+   - Coverage now vs then
+
+3. Report:
+```
+CHECKPOINT COMPARISON: $NAME
+============================
+Files changed: X
+Tests: +Y passed / -Z failed
+Coverage: +X% / -Y%
+Build: [PASS/FAIL]
+```
+
+## List Checkpoints
+
+Show all checkpoints with:
+- Name
+- Timestamp
+- Git SHA
+- Status (current, behind, ahead)
+
+## Workflow
+
+Typical checkpoint flow:
+
+```
+[Start] --> /checkpoint create "feature-start"
+   |
+[Implement] --> /checkpoint create "core-done"
+   |
+[Test] --> /checkpoint verify "core-done"
+   |
+[Refactor] --> /checkpoint create "refactor-done"
+   |
+[PR] --> /checkpoint verify "feature-start"
+```
+
+## Arguments
+
+$ARGUMENTS:
+- `create <name>` - Create named checkpoint
+- `verify <name>` - Verify against named checkpoint
+- `list` - Show all checkpoints
+- `clear` - Remove old checkpoints (keeps last 5)

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

@@ -0,0 +1,23 @@
+---
+description: Legacy slash-entry shim for the nanoclaw-repl skill. Prefer the skill directly.
+---
+
+# Claw Command (Legacy Shim)
+
+Use this only if you still reach for `/claw` from muscle memory. The maintained implementation lives in `skills/nanoclaw-repl/SKILL.md`.
+
+## Canonical Surface
+
+- Prefer the `nanoclaw-repl` skill directly.
+- Keep this file only as a compatibility entry point while command-first usage is retired.
+
+## Arguments
+
+`$ARGUMENTS`
+
+## Delegation
+
+Apply the `nanoclaw-repl` skill and keep the response focused on operating or extending `scripts/claw.js`.
+- If the user wants to run it, use `node scripts/claw.js` or `npm run claw`.
+- If the user wants to extend it, preserve the zero-dependency and markdown-backed session model.
+- If the request is really about long-running orchestration rather than NanoClaw itself, redirect to `dmux-workflows` or `autonomous-agent-harness`.

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

@@ -0,0 +1,289 @@
+---
+description: Code review — local uncommitted changes or GitHub PR (pass PR number/URL for PR mode)
+argument-hint: [pr-number | pr-url | blank for local review]
+---
+
+# Code Review
+
+> PR review mode adapted from PRPs-agentic-eng by Wirasm. Part of the PRP workflow series.
+
+**Input**: $ARGUMENTS
+
+---
+
+## Mode Selection
+
+If `$ARGUMENTS` contains a PR number, PR URL, or `--pr`:
+→ Jump to **PR Review Mode** below.
+
+Otherwise:
+→ Use **Local Review Mode**.
+
+---
+
+## Local Review Mode
+
+Comprehensive security and quality review of uncommitted changes.
+
+### Phase 1 — GATHER
+
+```bash
+git diff --name-only HEAD
+```
+
+If no changed files, stop: "Nothing to review."
+
+### Phase 2 — REVIEW
+
+Read each changed file in full. Check for:
+
+**Security Issues (CRITICAL):**
+- Hardcoded credentials, API keys, tokens
+- SQL injection vulnerabilities
+- XSS vulnerabilities
+- Missing input validation
+- Insecure dependencies
+- Path traversal risks
+
+**Code Quality (HIGH):**
+- Functions > 50 lines
+- Files > 800 lines
+- Nesting depth > 4 levels
+- Missing error handling
+- console.log statements
+- TODO/FIXME comments
+- Missing JSDoc for public APIs
+
+**Best Practices (MEDIUM):**
+- Mutation patterns (use immutable instead)
+- Emoji usage in code/comments
+- Missing tests for new code
+- Accessibility issues (a11y)
+
+### Phase 3 — REPORT
+
+Generate report with:
+- Severity: CRITICAL, HIGH, MEDIUM, LOW
+- File location and line numbers
+- Issue description
+- Suggested fix
+
+Block commit if CRITICAL or HIGH issues found.
+Never approve code with security vulnerabilities.
+
+---
+
+## PR Review Mode
+
+Comprehensive GitHub PR review — fetches diff, reads full files, runs validation, posts review.
+
+### Phase 1 — FETCH
+
+Parse input to determine PR:
+
+| Input | Action |
+|---|---|
+| Number (e.g. `42`) | Use as PR number |
+| URL (`github.com/.../pull/42`) | Extract PR number |
+| Branch name | Find PR via `gh pr list --head <branch>` |
+
+```bash
+gh pr view <NUMBER> --json number,title,body,author,baseRefName,headRefName,changedFiles,additions,deletions
+gh pr diff <NUMBER>
+```
+
+If PR not found, stop with error. Store PR metadata for later phases.
+
+### Phase 2 — CONTEXT
+
+Build review context:
+
+1. **Project rules** — Read `CLAUDE.md`, `.claude/docs/`, and any contributing guidelines
+2. **PRP artifacts** — Check `.claude/PRPs/reports/` and `.claude/PRPs/plans/` for implementation context related to this PR
+3. **PR intent** — Parse PR description for goals, linked issues, test plans
+4. **Changed files** — List all modified files and categorize by type (source, test, config, docs)
+
+### Phase 3 — REVIEW
+
+Read each changed file **in full** (not just the diff hunks — you need surrounding context).
+
+For PR reviews, fetch the full file contents at the PR head revision:
+```bash
+gh pr diff <NUMBER> --name-only | while IFS= read -r file; do
+  gh api "repos/{owner}/{repo}/contents/$file?ref=<head-branch>" --jq '.content' | base64 -d
+done
+```
+
+Apply the review checklist across 7 categories:
+
+| Category | What to Check |
+|---|---|
+| **Correctness** | Logic errors, off-by-ones, null handling, edge cases, race conditions |
+| **Type Safety** | Type mismatches, unsafe casts, `any` usage, missing generics |
+| **Pattern Compliance** | Matches project conventions (naming, file structure, error handling, imports) |
+| **Security** | Injection, auth gaps, secret exposure, SSRF, path traversal, XSS |
+| **Performance** | N+1 queries, missing indexes, unbounded loops, memory leaks, large payloads |
+| **Completeness** | Missing tests, missing error handling, incomplete migrations, missing docs |
+| **Maintainability** | Dead code, magic numbers, deep nesting, unclear naming, missing types |
+
+Assign severity to each finding:
+
+| Severity | Meaning | Action |
+|---|---|---|
+| **CRITICAL** | Security vulnerability or data loss risk | Must fix before merge |
+| **HIGH** | Bug or logic error likely to cause issues | Should fix before merge |
+| **MEDIUM** | Code quality issue or missing best practice | Fix recommended |
+| **LOW** | Style nit or minor suggestion | Optional |
+
+### Phase 4 — VALIDATE
+
+Run available validation commands:
+
+Detect the project type from config files (`package.json`, `Cargo.toml`, `go.mod`, `pyproject.toml`, etc.), then run the appropriate commands:
+
+**Node.js / TypeScript** (has `package.json`):
+```bash
+npm run typecheck 2>/dev/null || npx tsc --noEmit 2>/dev/null  # Type check
+npm run lint                                                    # Lint
+npm test                                                        # Tests
+npm run build                                                   # Build
+```
+
+**Rust** (has `Cargo.toml`):
+```bash
+cargo clippy -- -D warnings  # Lint
+cargo test                   # Tests
+cargo build                  # Build
+```
+
+**Go** (has `go.mod`):
+```bash
+go vet ./...    # Lint
+go test ./...   # Tests
+go build ./...  # Build
+```
+
+**Python** (has `pyproject.toml` / `setup.py`):
+```bash
+pytest  # Tests
+```
+
+Run only the commands that apply to the detected project type. Record pass/fail for each.
+
+### Phase 5 — DECIDE
+
+Form recommendation based on findings:
+
+| Condition | Decision |
+|---|---|
+| Zero CRITICAL/HIGH issues, validation passes | **APPROVE** |
+| Only MEDIUM/LOW issues, validation passes | **APPROVE** with comments |
+| Any HIGH issues or validation failures | **REQUEST CHANGES** |
+| Any CRITICAL issues | **BLOCK** — must fix before merge |
+
+Special cases:
+- Draft PR → Always use **COMMENT** (not approve/block)
+- Only docs/config changes → Lighter review, focus on correctness
+- Explicit `--approve` or `--request-changes` flag → Override decision (but still report all findings)
+
+### Phase 6 — REPORT
+
+Create review artifact at `.claude/PRPs/reviews/pr-<NUMBER>-review.md`:
+
+```markdown
+# PR Review: #<NUMBER> — <TITLE>
+
+**Reviewed**: <date>
+**Author**: <author>
+**Branch**: <head> → <base>
+**Decision**: APPROVE | REQUEST CHANGES | BLOCK
+
+## Summary
+<1-2 sentence overall assessment>
+
+## Findings
+
+### CRITICAL
+<findings or "None">
+
+### HIGH
+<findings or "None">
+
+### MEDIUM
+<findings or "None">
+
+### LOW
+<findings or "None">
+
+## Validation Results
+
+| Check | Result |
+|---|---|
+| Type check | Pass / Fail / Skipped |
+| Lint | Pass / Fail / Skipped |
+| Tests | Pass / Fail / Skipped |
+| Build | Pass / Fail / Skipped |
+
+## Files Reviewed
+<list of files with change type: Added/Modified/Deleted>
+```
+
+### Phase 7 — PUBLISH
+
+Post the review to GitHub:
+
+```bash
+# If APPROVE
+gh pr review <NUMBER> --approve --body "<summary of review>"
+
+# If REQUEST CHANGES
+gh pr review <NUMBER> --request-changes --body "<summary with required fixes>"
+
+# If COMMENT only (draft PR or informational)
+gh pr review <NUMBER> --comment --body "<summary>"
+```
+
+For inline comments on specific lines, use the GitHub review comments API:
+```bash
+gh api "repos/{owner}/{repo}/pulls/<NUMBER>/comments" \
+  -f body="<comment>" \
+  -f path="<file>" \
+  -F line=<line-number> \
+  -f side="RIGHT" \
+  -f commit_id="$(gh pr view <NUMBER> --json headRefOid --jq .headRefOid)"
+```
+
+Alternatively, post a single review with multiple inline comments at once:
+```bash
+gh api "repos/{owner}/{repo}/pulls/<NUMBER>/reviews" \
+  -f event="COMMENT" \
+  -f body="<overall summary>" \
+  --input comments.json  # [{"path": "file", "line": N, "body": "comment"}, ...]
+```
+
+### Phase 8 — OUTPUT
+
+Report to user:
+
+```
+PR #<NUMBER>: <TITLE>
+Decision: <APPROVE|REQUEST_CHANGES|BLOCK>
+
+Issues: <critical_count> critical, <high_count> high, <medium_count> medium, <low_count> low
+Validation: <pass_count>/<total_count> checks passed
+
+Artifacts:
+  Review: .claude/PRPs/reviews/pr-<NUMBER>-review.md
+  GitHub: <PR URL>
+
+Next steps:
+  - <contextual suggestions based on decision>
+```
+
+---
+
+## Edge Cases
+
+- **No `gh` CLI**: Fall back to local-only review (read the diff, skip GitHub publish). Warn user.
+- **Diverged branches**: Suggest `git fetch origin && git rebase origin/<base>` before review.
+- **Large PRs (>50 files)**: Warn about review scope. Focus on source changes first, then tests, then config/docs.

package/.aider-ecc/commands/context-budget.md

@@ -0,0 +1,23 @@
+---
+description: Legacy slash-entry shim for the context-budget skill. Prefer the skill directly.
+---
+
+# Context Budget Optimizer (Legacy Shim)
+
+Use this only if you still invoke `/context-budget`. The maintained workflow lives in `skills/context-budget/SKILL.md`.
+
+## Canonical Surface
+
+- Prefer the `context-budget` skill directly.
+- Keep this file only as a compatibility entry point.
+
+## Arguments
+
+$ARGUMENTS
+
+## Delegation
+
+Apply the `context-budget` skill.
+- Pass through `--verbose` if the user supplied it.
+- Assume a 200K context window unless the user specified otherwise.
+- Return the skill's inventory, issue detection, and prioritized savings report without re-implementing the scan here.