kodelyth-ecc 2.19.0 → 2.21.0

package/.aider-ecc/skills/agent-handoff/SKILL.md

@@ -1,184 +0,0 @@
----
-name: agent-handoff
-description: >
-  How to chain ECC specialist agents for multi-step problems —
-  pair-programmer → tdd-guide → code-reviewer → security-reviewer.
-  Use when one agent finishes its job and the next logical step needs
-  a different specialist. Documents the standard handoff protocol so
-  agents pass context cleanly.
----
-
-# Agent Handoff Protocol
-
-Single agents handle single concerns. Real engineering tasks span multiple concerns. **Handoffs** are how ECC chains agents without losing context.
-
-## The 3-Line Handoff Protocol
-
-When an agent finishes its scope and the next step needs a different specialist, it ends with exactly this shape:
-
-```
-─────────────────────────────────────
-HANDOFF
-  From: <current-agent>
-  To:   <next-agent>
-  Why:  <one-line reason>
-  Carry: <what the next agent needs to know>
-─────────────────────────────────────
-```
-
-Then **stop**. The next agent picks up from `Carry:`.
-
-## Standard Chains
-
-These are the most common multi-agent flows. Memorize them.
-
-### Build something new (clean path)
-
-```
-pair-programmer  →  tdd-guide  →  code-reviewer  →  api-guardian (if API)
-                                              →  security-reviewer (if sensitive)
-                                              →  ux-reviewer (if UI)
-```
-
-`pair-programmer` agrees on approach. `tdd-guide` writes failing tests first. The implementer writes code. `code-reviewer` checks it. Specialist reviewers check their domain.
-
-### Bug in production
-
-```
-debug-detective  →  tdd-guide          →  refactor-cleaner (optional)
-                 (root cause)        (regression test)
-```
-
-Always add a regression test after a real-bug fix. Always.
-
-### Refactor a module
-
-```
-code-explorer    →  refactor-cleaner   →  tdd-guide        →  code-reviewer
-(map dependencies)  (cleanup)          (verify behavior)
-```
-
-### Performance investigation
-
-```
-performance-optimizer  →  tdd-guide       →  code-reviewer
-                       (perf regression test)
-```
-
-### API change
-
-```
-api-guardian  →  pair-programmer  →  tdd-guide  →  doc-updater
-(blast radius)  (impl approach)                   (changelog)
-```
-
-### Security audit
-
-```
-security-reviewer  →  tdd-guide               →  release-captain
-                   (security regression test)  (patch release)
-```
-
-### Open-source a private project
-
-```
-opensource-forker  →  opensource-sanitizer  →  opensource-packager  →  release-captain
-(make a clean fork) (strip secrets/PII)      (README, license, examples)  (cut v0.1.0)
-```
-
-### Framework migration
-
-```
-migration-guide  →  pair-programmer  →  tdd-guide  →  pr-test-analyzer
-(phase plan)        (per-phase impl)              (verify coverage on PR)
-```
-
-### Build is broken
-
-```
-build-error-resolver  →  dependency-doctor (if dep issue)
-                      →  env-debugger (if env issue)
-                      →  debug-detective (if it's actually a runtime bug surfacing at build)
-```
-
-### CI is flaky
-
-```
-flake-hunter  →  tdd-guide       →  release-captain (if it gates a release)
-              (deterministic test)
-```
-
-### Git is on fire
-
-```
-git-rescue  →  release-captain (if a release was midway)
-```
-
-## Carry Field — What to Pass Forward
-
-The `Carry:` line is the most important. Bad carry breaks the chain.
-
-**Good carry:**
-> "Bug is in `processPayment()` line 142 — race between `lockBalance()` and `commitTx()`. The lock returns before the DB transaction is durable. Add a regression test that simulates a 50ms commit delay and asserts no double-spend."
-
-**Bad carry:**
-> "There was a bug, please test it"
-
-The next agent should be able to start work from `Carry:` alone, without re-reading the whole conversation.
-
-## When NOT to Hand Off
-
-- The current agent's job isn't actually done. Finish it.
-- The user explicitly said "just do this one thing." Respect it.
-- The next step is **trivial** and a handoff would slow it down (e.g., a one-line change). Just do it.
-- The user is **already in flow** and a handoff context-switch would interrupt them. Wait for a natural pause.
-
-## Parallel Handoffs
-
-Some problems need multiple agents at once, not in sequence:
-
-```
-"Building a new payment endpoint" →
-
-  [PARALLEL]
-   ├─ api-guardian       (contract review)
-   ├─ security-reviewer  (auth, input validation, idempotency)
-   └─ pair-programmer    (overall approach)
-
-  [SEQUENTIAL after agreement]
-   tdd-guide → implementer → code-reviewer
-```
-
-Announce the parallel set up front so the user knows what's happening:
-
-```
-This touches three concerns at once. I'm consulting:
-  • api-guardian      — for contract design
-  • security-reviewer — for auth & validation
-  • pair-programmer   — for overall structure
-
-Then we'll move to tests + implementation.
-```
-
-## Handoff Hygiene
-
-- **Always** name both agents (from/to)
-- **Always** justify the handoff in one line (why this specialist now?)
-- **Always** package the carry — the next agent should not need to re-investigate
-- **Never** chain more than 4 agents in a single response — that's a sign the task is too big and needs decomposition (use `planner`)
-
-## Self-Handoff Rule
-
-An agent may **stay in role** for the next step if it's still within its specialty. Don't fake a handoff just because the conversation continues:
-
-- `debug-detective` may continue after finding the cause to **explain** the cause — that's still debugging.
-- `code-reviewer` may continue to suggest specific fixes — still review scope.
-- But `code-reviewer` writing the actual fix at scale → hand off to the implementer (or appropriate language reviewer with `code-architect` for blueprint).
-
-## The Master Conductor: kodelyth-advisor
-
-When in doubt about whom to hand off to, the user can always invoke `kodelyth-advisor`. The advisor doesn't do the work — it picks the right specialist and routes.
-
-```
-Any agent  →  kodelyth-advisor (if next step is unclear)  →  Right specialist
-```

package/.aider-ecc/skills/agent-harness-construction/SKILL.md

@@ -1,73 +0,0 @@
----
-name: agent-harness-construction
-description: Design and optimize AI agent action spaces, tool definitions, and observation formatting for higher completion rates.
-origin: ECC
----
-
-# Agent Harness Construction
-
-Use this skill when you are improving how an agent plans, calls tools, recovers from errors, and converges on completion.
-
-## Core Model
-
-Agent output quality is constrained by:
-1. Action space quality
-2. Observation quality
-3. Recovery quality
-4. Context budget quality
-
-## Action Space Design
-
-1. Use stable, explicit tool names.
-2. Keep inputs schema-first and narrow.
-3. Return deterministic output shapes.
-4. Avoid catch-all tools unless isolation is impossible.
-
-## Granularity Rules
-
-- Use micro-tools for high-risk operations (deploy, migration, permissions).
-- Use medium tools for common edit/read/search loops.
-- Use macro-tools only when round-trip overhead is the dominant cost.
-
-## Observation Design
-
-Every tool response should include:
-- `status`: success|warning|error
-- `summary`: one-line result
-- `next_actions`: actionable follow-ups
-- `artifacts`: file paths / IDs
-
-## Error Recovery Contract
-
-For every error path, include:
-- root cause hint
-- safe retry instruction
-- explicit stop condition
-
-## Context Budgeting
-
-1. Keep system prompt minimal and invariant.
-2. Move large guidance into skills loaded on demand.
-3. Prefer references to files over inlining long documents.
-4. Compact at phase boundaries, not arbitrary token thresholds.
-
-## Architecture Pattern Guidance
-
-- ReAct: best for exploratory tasks with uncertain path.
-- Function-calling: best for structured deterministic flows.
-- Hybrid (recommended): ReAct planning + typed tool execution.
-
-## Benchmarking
-
-Track:
-- completion rate
-- retries per task
-- pass@1 and pass@3
-- cost per successful task
-
-## Anti-Patterns
-
-- Too many tools with overlapping semantics.
-- Opaque tool output with no recovery hints.
-- Error-only output without next steps.
-- Context overloading with irrelevant references.

package/.aider-ecc/skills/agent-introspection-debugging/SKILL.md

@@ -1,153 +0,0 @@
----
-name: agent-introspection-debugging
-description: Structured self-debugging workflow for AI agent failures using capture, diagnosis, contained recovery, and introspection reports.
-origin: ECC
----
-
-# Agent Introspection Debugging
-
-Use this skill when an agent run is failing repeatedly, consuming tokens without progress, looping on the same tools, or drifting away from the intended task.
-
-This is a workflow skill, not a hidden runtime. It teaches the agent to debug itself systematically before escalating to a human.
-
-## When to Activate
-
-- Maximum tool call / loop-limit failures
-- Repeated retries with no forward progress
-- Context growth or prompt drift that starts degrading output quality
-- File-system or environment state mismatch between expectation and reality
-- Tool failures that are likely recoverable with diagnosis and a smaller corrective action
-
-## Scope Boundaries
-
-Activate this skill for:
-- capturing failure state before retrying blindly
-- diagnosing common agent-specific failure patterns
-- applying contained recovery actions
-- producing a structured human-readable debug report
-
-Do not use this skill as the primary source for:
-- feature verification after code changes; use `verification-loop`
-- framework-specific debugging when a narrower ECC skill already exists
-- runtime promises the current harness cannot enforce automatically
-
-## Four-Phase Loop
-
-### Phase 1: Failure Capture
-
-Before trying to recover, record the failure precisely.
-
-Capture:
-- error type, message, and stack trace when available
-- last meaningful tool call sequence
-- what the agent was trying to do
-- current context pressure: repeated prompts, oversized pasted logs, duplicated plans, or runaway notes
-- current environment assumptions: cwd, branch, relevant service state, expected files
-
-Minimum capture template:
-
-```markdown
-## Failure Capture
-- Session / task:
-- Goal in progress:
-- Error:
-- Last successful step:
-- Last failed tool / command:
-- Repeated pattern seen:
-- Environment assumptions to verify:
-```
-
-### Phase 2: Root-Cause Diagnosis
-
-Match the failure to a known pattern before changing anything.
-
-| Pattern | Likely Cause | Check |
-| --- | --- | --- |
-| Maximum tool calls / repeated same command | loop or no-exit observer path | inspect the last N tool calls for repetition |
-| Context overflow / degraded reasoning | unbounded notes, repeated plans, oversized logs | inspect recent context for duplication and low-signal bulk |
-| `ECONNREFUSED` / timeout | service unavailable or wrong port | verify service health, URL, and port assumptions |
-| `429` / quota exhaustion | retry storm or missing backoff | count repeated calls and inspect retry spacing |
-| file missing after write / stale diff | race, wrong cwd, or branch drift | re-check path, cwd, git status, and actual file existence |
-| tests still failing after “fix” | wrong hypothesis | isolate the exact failing test and re-derive the bug |
-
-Diagnosis questions:
-- is this a logic failure, state failure, environment failure, or policy failure?
-- did the agent lose the real objective and start optimizing the wrong subtask?
-- is the failure deterministic or transient?
-- what is the smallest reversible action that would validate the diagnosis?
-
-### Phase 3: Contained Recovery
-
-Recover with the smallest action that changes the diagnosis surface.
-
-Safe recovery actions:
-- stop repeated retries and restate the hypothesis
-- trim low-signal context and keep only the active goal, blockers, and evidence
-- re-check the actual filesystem / branch / process state
-- narrow the task to one failing command, one file, or one test
-- switch from speculative reasoning to direct observation
-- escalate to a human when the failure is high-risk or externally blocked
-
-Do not claim unsupported auto-healing actions like “reset agent state” or “update harness config” unless you are actually doing them through real tools in the current environment.
-
-Contained recovery checklist:
-
-```markdown
-## Recovery Action
-- Diagnosis chosen:
-- Smallest action taken:
-- Why this is safe:
-- What evidence would prove the fix worked:
-```
-
-### Phase 4: Introspection Report
-
-End with a report that makes the recovery legible to the next agent or human.
-
-```markdown
-## Agent Self-Debug Report
-- Session / task:
-- Failure:
-- Root cause:
-- Recovery action:
-- Result: success | partial | blocked
-- Token / time burn risk:
-- Follow-up needed:
-- Preventive change to encode later:
-```
-
-## Recovery Heuristics
-
-Prefer these interventions in order:
-
-1. Restate the real objective in one sentence.
-2. Verify the world state instead of trusting memory.
-3. Shrink the failing scope.
-4. Run one discriminating check.
-5. Only then retry.
-
-Bad pattern:
-- retrying the same action three times with slightly different wording
-
-Good pattern:
-- capture failure
-- classify the pattern
-- run one direct check
-- change the plan only if the check supports it
-
-## Integration with ECC
-
-- Use `verification-loop` after recovery if code was changed.
-- Use `continuous-learning-v2` when the failure pattern is worth turning into an instinct or later skill.
-- Use `council` when the issue is not technical failure but decision ambiguity.
-- Use `workspace-surface-audit` if the failure came from conflicting local state or repo drift.
-
-## Output Standard
-
-When this skill is active, do not end with “I fixed it” alone.
-
-Always provide:
-- the failure pattern
-- the root-cause hypothesis
-- the recovery action
-- the evidence that the situation is now better or still blocked

package/.aider-ecc/skills/agent-payment-x402/SKILL.md

@@ -1,178 +0,0 @@
----
-name: agent-payment-x402
-description: Add x402 payment execution to AI agents — per-task budgets, spending controls, and non-custodial wallets via MCP tools. Use when agents need to pay for APIs, services, or other agents.
-origin: community
----
-
-# Agent Payment Execution (x402)
-
-Enable AI agents to make autonomous payments with built-in spending controls. Uses the x402 HTTP payment protocol and MCP tools so agents can pay for external services, APIs, or other agents without custodial risk.
-
-## When to Use
-
-Use when: your agent needs to pay for an API call, purchase a service, settle with another agent, enforce per-task spending limits, or manage a non-custodial wallet. Pairs naturally with cost-aware-llm-pipeline and security-review skills.
-
-## How It Works
-
-### x402 Protocol
-x402 extends HTTP 402 (Payment Required) into a machine-negotiable flow. When a server returns `402`, the agent's payment tool automatically negotiates price, checks budget, signs a transaction, and retries — no human in the loop.
-
-### Spending Controls
-Every payment tool call enforces a `SpendingPolicy`:
-- **Per-task budget** — max spend for a single agent action
-- **Per-session budget** — cumulative limit across an entire session
-- **Allowlisted recipients** — restrict which addresses/services the agent can pay
-- **Rate limits** — max transactions per minute/hour
-
-### Non-Custodial Wallets
-Agents hold their own keys via ERC-4337 smart accounts. The orchestrator sets policy before delegation; the agent can only spend within bounds. No pooled funds, no custodial risk.
-
-## MCP Integration
-
-The payment layer exposes standard MCP tools that slot into any Claude Code or agent harness setup.
-
-> **Security note**: Always pin the package version. This tool manages private keys — unpinned `npx` installs introduce supply-chain risk.
-
-```json
-{
-  "mcpServers": {
-    "agentpay": {
-      "command": "npx",
-      "args": ["agentwallet-sdk@6.0.0"]
-    }
-  }
-}
-```
-
-### Available Tools (agent-callable)
-
-| Tool | Purpose |
-|------|---------|
-| `get_balance` | Check agent wallet balance |
-| `send_payment` | Send payment to address or ENS |
-| `check_spending` | Query remaining budget |
-| `list_transactions` | Audit trail of all payments |
-
-> **Note**: Spending policy is set by the **orchestrator** before delegating to the agent — not by the agent itself. This prevents agents from escalating their own spending limits. Configure policy via `set_policy` in your orchestration layer or pre-task hook, never as an agent-callable tool.
-
-## Examples
-
-### Budget enforcement in an MCP client
-
-When building an orchestrator that calls the agentpay MCP server, enforce budgets before dispatching paid tool calls.
-
-> **Prerequisites**: Install the package before adding the MCP config — `npx` without `-y` will prompt for confirmation in non-interactive environments, causing the server to hang: `npm install -g agentwallet-sdk@6.0.0`
-
-```typescript
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
-
-async function main() {
-  // 1. Validate credentials before constructing the transport.
-  //    A missing key must fail immediately — never let the subprocess start without auth.
-  const walletKey = process.env.WALLET_PRIVATE_KEY;
-  if (!walletKey) {
-    throw new Error("WALLET_PRIVATE_KEY is not set — refusing to start payment server");
-  }
-
-  // Connect to the agentpay MCP server via stdio transport.
-  // Whitelist only the env vars the server needs — never forward all of process.env
-  // to a third-party subprocess that manages private keys.
-  const transport = new StdioClientTransport({
-    command: "npx",
-    args: ["agentwallet-sdk@6.0.0"],
-    env: {
-      PATH: process.env.PATH ?? "",
-      NODE_ENV: process.env.NODE_ENV ?? "production",
-      WALLET_PRIVATE_KEY: walletKey,
-    },
-  });
-  const agentpay = new Client({ name: "orchestrator", version: "1.0.0" });
-  await agentpay.connect(transport);
-
-  // 2. Set spending policy before delegating to the agent.
-  //    Always verify success — a silent failure means no controls are active.
-  const policyResult = await agentpay.callTool({
-    name: "set_policy",
-    arguments: {
-      per_task_budget: 0.50,
-      per_session_budget: 5.00,
-      allowlisted_recipients: ["api.example.com"],
-    },
-  });
-  if (policyResult.isError) {
-    throw new Error(
-      `Failed to set spending policy — do not delegate: ${JSON.stringify(policyResult.content)}`
-    );
-  }
-
-  // 3. Use preToolCheck before any paid action
-  await preToolCheck(agentpay, 0.01);
-}
-
-// Pre-tool hook: fail-closed budget enforcement with four distinct error paths.
-async function preToolCheck(agentpay: Client, apiCost: number): Promise<void> {
-  // Path 1: Reject invalid input (NaN/Infinity bypass the < comparison)
-  if (!Number.isFinite(apiCost) || apiCost < 0) {
-    throw new Error(`Invalid apiCost: ${apiCost} — action blocked`);
-  }
-
-  // Path 2: Transport/connectivity failure
-  let result;
-  try {
-    result = await agentpay.callTool({ name: "check_spending" });
-  } catch (err) {
-    throw new Error(`Payment service unreachable — action blocked: ${err}`);
-  }
-
-  // Path 3: Tool returned an error (e.g., auth failure, wallet not initialised)
-  if (result.isError) {
-    throw new Error(
-      `check_spending failed — action blocked: ${JSON.stringify(result.content)}`
-    );
-  }
-
-  // Path 4: Parse and validate the response shape
-  let remaining: number;
-  try {
-    const parsed = JSON.parse(
-      (result.content as Array<{ text: string }>)[0].text
-    );
-    if (!Number.isFinite(parsed?.remaining)) {
-      throw new TypeError("missing or non-finite 'remaining' field");
-    }
-    remaining = parsed.remaining;
-  } catch (err) {
-    throw new Error(
-      `check_spending returned unexpected format — action blocked: ${err}`
-    );
-  }
-
-  // Path 5: Budget exceeded
-  if (remaining < apiCost) {
-    throw new Error(
-      `Budget exceeded: need $${apiCost} but only $${remaining} remaining`
-    );
-  }
-}
-
-main().catch((err) => {
-  console.error(err);
-  process.exitCode = 1;
-});
-```
-
-## Best Practices
-
-- **Set budgets before delegation**: When spawning sub-agents, attach a SpendingPolicy via your orchestration layer. Never give an agent unlimited spend.
-- **Pin your dependencies**: Always specify an exact version in your MCP config (e.g., `agentwallet-sdk@6.0.0`). Verify package integrity before deploying to production.
-- **Audit trails**: Use `list_transactions` in post-task hooks to log what was spent and why.
-- **Fail closed**: If the payment tool is unreachable, block the paid action — don't fall back to unmetered access.
-- **Pair with security-review**: Payment tools are high-privilege. Apply the same scrutiny as shell access.
-- **Test with testnets first**: Use Base Sepolia for development; switch to Base mainnet for production.
-
-## Production Reference
-
-- **npm**: [`agentwallet-sdk`](https://www.npmjs.com/package/agentwallet-sdk)
-- **Merged into NVIDIA NeMo Agent Toolkit**: [PR #17](https://github.com/NVIDIA/NeMo-Agent-Toolkit-Examples/pull/17) — x402 payment tool for NVIDIA's agent examples
-- **Protocol spec**: [x402.org](https://x402.org)