compact-agent 1.1.0

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

@@ -0,0 +1,152 @@
+---
+name: agent-introspection-debugging
+description: Structured self-debugging workflow for AI agent failures using capture, diagnosis, contained recovery, and introspection reports.
+---
+
+# 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/resources/ecc/skills/agent-introspection-debugging/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Agent Introspection Debugging"
+  short_description: "Structured self-debugging for AI agent failures"
+  brand_color: "#0EA5E9"
+  default_prompt: "Use $agent-introspection-debugging to diagnose and recover from an AI agent failure."
+policy:
+  allow_implicit_invocation: true

package/resources/ecc/skills/agent-sort/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: agent-sort
+description: Build an evidence-backed ECC install plan for a specific repo by sorting skills, commands, rules, hooks, and extras into DAILY vs LIBRARY buckets using parallel repo-aware review passes. Use when ECC should be trimmed to what a project actually needs instead of loading the full bundle.
+---
+
+# Agent Sort
+
+Use this skill when a repo needs a project-specific ECC surface instead of the default full install.
+
+The goal is not to guess what "feels useful." The goal is to classify ECC components with evidence from the actual codebase.
+
+## When to Use
+
+- A project only needs a subset of ECC and full installs are too noisy
+- The repo stack is clear, but nobody wants to hand-curate skills one by one
+- A team wants a repeatable install decision backed by grep evidence instead of opinion
+- You need to separate always-loaded daily workflow surfaces from searchable library/reference surfaces
+- A repo has drifted into the wrong language, rule, or hook set and needs cleanup
+
+## Non-Negotiable Rules
+
+- Use the current repository as the source of truth, not generic preferences
+- Every DAILY decision must cite concrete repo evidence
+- LIBRARY does not mean "delete"; it means "keep accessible without loading by default"
+- Do not install hooks, rules, or scripts that the current repo cannot use
+- Prefer ECC-native surfaces; do not introduce a second install system
+
+## Outputs
+
+Produce these artifacts in order:
+
+1. DAILY inventory
+2. LIBRARY inventory
+3. install plan
+4. verification report
+5. optional `skill-library` router if the project wants one
+
+## Classification Model
+
+Use two buckets only:
+
+- `DAILY`
+  - should load every session for this repo
+  - strongly matched to the repo's language, framework, workflow, or operator surface
+- `LIBRARY`
+  - useful to retain, but not worth loading by default
+  - should remain reachable through search, router skill, or selective manual use
+
+## Evidence Sources
+
+Use repo-local evidence before making any classification:
+
+- file extensions
+- package managers and lockfiles
+- framework configs
+- CI and hook configs
+- build/test scripts
+- imports and dependency manifests
+- repo docs that explicitly describe the stack
+
+Useful commands include:
+
+```bash
+rg --files
+rg -n "typescript|react|next|supabase|django|spring|flutter|swift"
+cat package.json
+cat pyproject.toml
+cat Cargo.toml
+cat pubspec.yaml
+cat go.mod
+```
+
+## Parallel Review Passes
+
+If parallel subagents are available, split the review into these passes:
+
+1. Agents
+   - classify `agents/*`
+2. Skills
+   - classify `skills/*`
+3. Commands
+   - classify `commands/*`
+4. Rules
+   - classify `rules/*`
+5. Hooks and scripts
+   - classify hook surfaces, MCP health checks, helper scripts, and OS compatibility
+6. Extras
+   - classify contexts, examples, MCP configs, templates, and guidance docs
+
+If subagents are not available, run the same passes sequentially.
+
+## Core Workflow
+
+### 1. Read the repo
+
+Establish the real stack before classifying anything:
+
+- languages in use
+- frameworks in use
+- primary package manager
+- test stack
+- lint/format stack
+- deployment/runtime surface
+- operator integrations already present
+
+### 2. Build the evidence table
+
+For every candidate surface, record:
+
+- component path
+- component type
+- proposed bucket
+- repo evidence
+- short justification
+
+Use this format:
+
+```text
+skills/frontend-patterns | skill | DAILY | 84 .tsx files, next.config.ts present | core frontend stack
+skills/django-patterns   | skill | LIBRARY | no .py files, no pyproject.toml       | not active in this repo
+rules/typescript/*       | rules | DAILY | package.json + tsconfig.json            | active TS repo
+rules/python/*           | rules | LIBRARY | zero Python source files             | keep accessible only
+```
+
+### 3. Decide DAILY vs LIBRARY
+
+Promote to `DAILY` when:
+
+- the repo clearly uses the matching stack
+- the component is general enough to help every session
+- the repo already depends on the corresponding runtime or workflow
+
+Demote to `LIBRARY` when:
+
+- the component is off-stack
+- the repo might need it later, but not every day
+- it adds context overhead without immediate relevance
+
+### 4. Build the install plan
+
+Translate the classification into action:
+
+- DAILY skills -> install or keep in `.claude/skills/`
+- DAILY commands -> keep as explicit shims only if still useful
+- DAILY rules -> install only matching language sets
+- DAILY hooks/scripts -> keep only compatible ones
+- LIBRARY surfaces -> keep accessible through search or `skill-library`
+
+If the repo already uses selective installs, update that plan instead of creating another system.
+
+### 5. Create the optional library router
+
+If the project wants a searchable library surface, create:
+
+- `.claude/skills/skill-library/SKILL.md`
+
+That router should contain:
+
+- a short explanation of DAILY vs LIBRARY
+- grouped trigger keywords
+- where the library references live
+
+Do not duplicate every skill body inside the router.
+
+### 6. Verify the result
+
+After the plan is applied, verify:
+
+- every DAILY file exists where expected
+- stale language rules were not left active
+- incompatible hooks were not installed
+- the resulting install actually matches the repo stack
+
+Return a compact report with:
+
+- DAILY count
+- LIBRARY count
+- removed stale surfaces
+- open questions
+
+## Handoffs
+
+If the next step is interactive installation or repair, hand off to:
+
+- `configure-ecc`
+
+If the next step is overlap cleanup or catalog review, hand off to:
+
+- `skill-stocktake`
+
+If the next step is broader context trimming, hand off to:
+
+- `strategic-compact`
+
+## Output Format
+
+Return the result in this order:
+
+```text
+STACK
+- language/framework/runtime summary
+
+DAILY
+- always-loaded items with evidence
+
+LIBRARY
+- searchable/reference items with evidence
+
+INSTALL PLAN
+- what should be installed, removed, or routed
+
+VERIFICATION
+- checks run and remaining gaps
+```

package/resources/ecc/skills/agent-sort/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Agent Sort"
+  short_description: "Evidence-backed ECC install planning"
+  brand_color: "#0EA5E9"
+  default_prompt: "Use $agent-sort to build an evidence-backed ECC install plan."
+policy:
+  allow_implicit_invocation: true