compact-agent 1.10.0 → 1.11.0

package/resources/ecc/skills/ecc-guide/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: ecc-guide
+description: Guide users through ECC's current agents, skills, commands, hooks, rules, install profiles, and project onboarding by reading the live repository surface before answering.
+origin: community
+---
+
+# ECC Guide
+
+Use this skill when a user needs help understanding, navigating, installing, or choosing parts of Everything Claude Code.
+
+## When To Use
+
+Use this skill when the user:
+
+- asks what ECC includes
+- wants help finding a skill, command, agent, hook, rule, or install profile
+- is new to the repository and needs a guided path
+- asks "how do I do X with ECC?"
+- asks which ECC components fit a project
+- needs a lightweight explanation of how commands, skills, agents, hooks, and rules relate
+- is confused by install paths, duplicate installs, reset/uninstall, or selective install options
+
+## Core Principle
+
+Answer from current files, not memory. ECC changes quickly, so hard-coded catalog counts, feature lists, and install instructions go stale.
+
+When the ECC repository is available, inspect the relevant files before giving a concrete answer:
+
+```bash
+node scripts/ci/catalog.js --json
+find skills -maxdepth 2 -name SKILL.md | sort
+find commands -maxdepth 1 -name '*.md' | sort
+find agents -maxdepth 1 -name '*.md' | sort
+node scripts/install-plan.js --list-profiles
+node scripts/install-plan.js --list-components --json
+```
+
+Use the smallest set of reads needed for the user's question.
+
+## Repository Map
+
+- `README.md`: install paths, uninstall/reset guidance, public positioning, FAQs
+- `AGENTS.md`: contributor guidance and project structure
+- `agent.yaml`: exported gitagent surface and command list
+- `commands/`: maintained slash-command compatibility shims
+- `skills/*/SKILL.md`: reusable workflows and domain playbooks
+- `agents/*.md`: delegated subagent role prompts
+- `rules/`: language and harness rules
+- `hooks/README.md`, `hooks/hooks.json`, `scripts/hooks/`: hook behavior and safety gates
+- `manifests/install-*.json`: selective install modules, components, profiles, and target support
+- `docs/`: harness guides, architecture notes, translated docs, release docs
+
+## Response Style
+
+Lead with the answer, then give the next action. Most users do not need a full catalog dump.
+
+Good first response shape:
+
+1. what to use
+2. why it fits
+3. exact file or command to inspect
+4. one next command or question
+
+Avoid:
+
+- listing every skill or command by default
+- repeating large README sections
+- recommending retired command shims when a skill-first path exists
+- claiming a component exists without checking the filesystem
+- replacing install guidance with manual copy commands when the managed installer supports the target
+
+## Common Tasks
+
+### New User Onboarding
+
+Give a short menu:
+
+- install or reset ECC
+- pick skills for a project
+- understand commands vs skills
+- inspect hooks and safety behavior
+- run a harness audit
+- find a specific workflow
+
+Point to `README.md` for install/reset and `/project-init` for project-specific onboarding.
+
+### Feature Discovery
+
+For "what should I use for X?":
+
+1. Search `skills/`, `commands/`, and `agents/`.
+2. Prefer skills as the primary workflow surface.
+3. Use commands only when they are a maintained compatibility shim or a user explicitly wants slash-command behavior.
+4. Mention agents when delegation is useful.
+
+Useful searches:
+
+```bash
+rg -n "<query>" skills commands agents docs
+find skills -maxdepth 2 -name SKILL.md | sort
+```
+
+### Install Guidance
+
+Use managed install paths:
+
+```bash
+node scripts/install-plan.js --list-profiles
+node scripts/install-plan.js --profile minimal --target claude --json
+node scripts/install-apply.js --profile minimal --target claude --dry-run
+```
+
+For specific skill installs:
+
+```bash
+node scripts/install-plan.js --skills <skill-id> --target claude --json
+node scripts/install-apply.js --skills <skill-id> --target claude --dry-run
+```
+
+Warn users not to stack plugin installs and full manual/profile installs unless they intentionally want duplicate surfaces.
+
+### Project Onboarding
+
+Use `/project-init` when the user wants ECC configured for a target repo. The expected sequence is:
+
+1. detect the stack from project files
+2. resolve a dry-run install plan
+3. inspect existing `CLAUDE.md` and settings files
+4. ask before applying changes
+5. keep generated guidance minimal and repo-specific
+
+### Troubleshooting
+
+Ask for the target harness and install path first, then inspect:
+
+- plugin install metadata
+- `.claude/`, `.cursor/`, `.codex/`, `.gemini/`, `.opencode/`, `.codebuddy/`, `.joycode/`, or `.qwen/`
+- `hooks/hooks.json`
+- install-state files
+- relevant command/skill files
+
+For repo health, suggest:
+
+```bash
+npm run harness:audit -- --format text
+npm run observability:ready
+npm test
+```
+
+## Output Templates
+
+### Short Recommendation
+
+```text
+Use <skill-or-command>. It fits because <reason>.
+
+Canonical file: <path>
+Verify with: <command>
+Next: <one concrete action>
+```
+
+### Search Results
+
+```text
+Best matches:
+- <path>: <why it matters>
+- <path>: <why it matters>
+
+Recommendation: <which one to use first and why>
+```
+
+### Install Plan Summary
+
+```text
+Detected: <stack evidence>
+Target: <harness>
+Plan: <profile/modules/skills>
+Dry run: <command>
+Would change: <paths>
+Needs approval before apply: <yes/no>
+```
+
+## Related Surfaces
+
+- `/project-init`: stack-aware onboarding plan for a target repo
+- `/harness-audit`: deterministic readiness scorecard
+- `/skill-health`: skill quality review
+- `/skill-create`: generate a new skill from local git history
+- `/security-scan`: inspect Claude/OpenCode configuration security

package/resources/ecc/skills/ecc-tools-cost-audit/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: ecc-tools-cost-audit
+description: Evidence-first ECC Tools burn and billing audit workflow. Use when investigating runaway PR creation, quota bypass, premium-model leakage, duplicate jobs, or GitHub App cost spikes in the ECC Tools repo.
+origin: ECC
+---
+
+# ECC Tools Cost Audit
+
+Use this skill when the user suspects the ECC Tools GitHub App is burning cost, over-creating PRs, bypassing usage limits, or routing free users into premium analysis paths.
+
+This is a focused operator workflow for the sibling [ECC-Tools](../../ECC-Tools) repo. It is not a generic billing skill and it is not a repo-wide code review pass.
+
+## Skill Stack
+
+Pull these ECC-native skills into the workflow when relevant:
+
+- `autonomous-loops` for bounded multi-step audits that cross webhooks, queues, billing, and retries
+- `agentic-engineering` for tracing the request path into discrete, provable units
+- `customer-billing-ops` when repo behavior and customer-impact math must be separated cleanly
+- `search-first` before inventing helpers or re-implementing repo-local utilities
+- `security-review` when auth, usage gates, entitlements, or secrets are touched
+- `verification-loop` for proving rerun safety and exact post-fix state
+- `tdd-workflow` when the fix needs regression coverage in the worker, router, or billing paths
+
+## When To Use
+
+- user says ECC Tools burn rate, PR recursion, over-created PRs, usage-limit bypass, or premium-model leakage
+- the task is in the sibling `ECC-Tools` repo and depends on webhook handlers, queue workers, usage reservation, PR creation logic, or paid-gate enforcement
+- a customer report says the app created too many PRs, billed incorrectly, or analyzed code without producing a usable result
+
+## Scope Guardrails
+
+- work in the sibling `ECC-Tools` repo, not in `everything-claude-code`
+- start read-only unless the user clearly asked for a fix
+- do not mutate unrelated billing, checkout, or UI flows while tracing analysis burn
+- treat app-generated branches and app-generated PRs as red-flag recursion paths until proved otherwise
+- separate three things explicitly:
+  - repo-side burn root cause
+  - customer-facing billing impact
+  - product or entitlement gaps that need backlog follow-up
+
+## Workflow
+
+### 1. Freeze repo scope
+
+- switch into the sibling `ECC-Tools` repo
+- check branch and local diff first
+- identify the exact surface under audit:
+  - webhook router
+  - queue producer
+  - queue consumer
+  - PR creation path
+  - usage reservation / billing path
+  - model routing path
+
+### 2. Trace ingress before theorizing
+
+- inspect `src/index.*` or the main entrypoint first
+- map every enqueue path before suggesting a fix
+- confirm which GitHub events share a queue type
+- confirm whether push, pull_request, synchronize, comment, or manual re-run events can converge on the same expensive path
+
+### 3. Trace the worker and side effects
+
+- inspect the queue consumer or scheduled worker that handles analysis
+- confirm whether a queued analysis always ends in:
+  - PR creation
+  - branch creation
+  - file updates
+  - premium model calls
+  - usage increments
+- if analysis can spend tokens and then fail before output is persisted, classify it as burn-with-broken-output
+
+### 4. Audit the high-signal burn paths
+
+#### PR multiplication
+
+- inspect PR helpers and branch naming
+- check dedupe, synchronize-event handling, and existing-PR reuse
+- if app-generated branches can re-enter analysis, treat that as a priority-0 recursion risk
+
+#### Quota bypass
+
+- inspect where quota is checked versus where usage is reserved or incremented
+- if quota is checked before enqueue but usage is charged only inside the worker, treat concurrent front-door passes as a real race
+
+#### Premium-model leakage
+
+- inspect model selection, tier branching, and provider routing
+- verify whether free or capped users can still hit premium analyzers when premium keys are present
+
+#### Retry burn
+
+- inspect retry loops, duplicate queue jobs, and deterministic failure reruns
+- if the same non-transient error can spend analysis repeatedly, fix that before quality improvements
+
+### 5. Fix in burn order
+
+If the user asked for code changes, prioritize fixes in this order:
+
+1. stop automatic PR multiplication
+2. stop quota bypass
+3. stop premium leakage
+4. stop duplicate-job fanout and pointless retries
+5. close rerun/update safety gaps
+
+Keep the pass bounded to one to three direct fixes unless the same root cause clearly spans multiple files.
+
+### 6. Verify with the smallest proving steps
+
+- rerun only the targeted tests or integration slices that cover the changed path
+- verify whether the burn path is now:
+  - blocked
+  - deduped
+  - downgraded to cheaper analysis
+  - or rejected early
+- state the final status exactly:
+  - changed locally
+  - verified locally
+  - pushed
+  - deployed
+  - still blocked
+
+## High-Signal Failure Patterns
+
+### 1. One queue type for all triggers
+
+If pushes, PR syncs, and manual audits all enqueue the same job and the worker always creates a PR, analysis equals PR spam.
+
+### 2. Post-enqueue usage reservation
+
+If usage is checked at the front door but only incremented in the worker, concurrent requests can all pass the gate and exceed quota.
+
+### 3. Free tier on premium path
+
+If free queued jobs can still route into Anthropic or another premium provider when keys exist, that is real spend leakage even if the user never sees the premium result.
+
+### 4. App-generated branches re-enter the webhook
+
+If `pull_request.synchronize`, branch pushes, or comment-triggered runs fire on app-owned branches, the app can recursively analyze its own output.
+
+### 5. Expensive work before persistence safety
+
+If the system can spend tokens and then fail on PR creation, file update, or branch collision, it is burning cost without shipping value.
+
+## Pitfalls
+
+- do not begin with broad repo wandering; settle webhook -> queue -> worker first
+- do not mix customer billing inference with code-backed product truth
+- do not fix lower-value quality issues before the highest-burn path is contained
+- do not claim burn is fixed until the narrow proving step was rerun
+- do not push or deploy unless the user asked
+- do not touch unrelated repo-local changes if they are already in progress
+
+## Verification
+
+- root causes cite exact file paths and code areas
+- fixes are ordered by burn impact, not code neatness
+- proving commands are named
+- final status distinguishes local change, verification, push, and deployment

package/resources/ecc/skills/email-ops/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: email-ops
+description: Evidence-first mailbox triage, drafting, send verification, and sent-mail-safe follow-up workflow for ECC. Use when the user wants to organize email, draft or send through the real mail surface, or prove what landed in Sent.
+origin: ECC
+---
+
+# Email Ops
+
+Use this when the real task is mailbox work: triage, drafting, replying, sending, or proving a message landed in Sent.
+
+This is not a generic writing skill. It is an operator workflow around the actual mail surface.
+
+## Skill Stack
+
+Pull these ECC-native skills into the workflow when relevant:
+
+- `brand-voice` before drafting anything user-facing
+- `investor-outreach` for investor, partner, or sponsor-facing mail
+- `customer-billing-ops` when the thread is a billing/support incident rather than generic correspondence
+- `knowledge-ops` when the message or thread should be captured into durable context afterward
+- `research-ops` when a reply depends on fresh external facts
+
+## When to Use
+
+- user asks to triage inbox or archive low-signal mail
+- user wants a draft, reply, or new outbound email
+- user wants to know whether a mail was already sent
+- the user wants proof of which account, thread, or Sent entry was used
+
+## Guardrails
+
+- draft first unless the user clearly asked for a live send
+- never claim a message was sent without a real Sent-folder or client-side confirmation
+- do not switch sender accounts casually; choose the account that matches the project and recipient
+- do not delete uncertain business mail during cleanup
+- if the task is really DM or iMessage work, hand off to `messages-ops`
+
+## Workflow
+
+### 1. Resolve the exact surface
+
+Before acting, settle:
+
+- which mailbox account
+- which thread or recipient
+- whether the task is triage, draft, reply, or send
+- whether the user wants draft-only or live send
+
+### 2. Read the thread before composing
+
+If replying:
+
+- read the existing thread
+- identify the last outbound touch
+- identify any commitments, deadlines, or unanswered questions
+
+If creating a new outbound:
+
+- identify warmth level
+- select the correct channel and sender account
+- pull `brand-voice` before drafting
+
+### 3. Draft, then verify
+
+For draft-only work:
+
+- produce the final copy
+- state sender, recipient, subject, and purpose
+
+For live-send work:
+
+- verify the exact final body first
+- send through the chosen mail surface
+- confirm the message landed in Sent or the equivalent sent-copy store
+
+### 4. Report exact state
+
+Use exact status words:
+
+- drafted
+- approval-pending
+- sent
+- blocked
+- awaiting verification
+
+If the send surface is blocked, preserve the draft and report the exact blocker instead of improvising a second transport without saying so.
+
+## Output Format
+
+```text
+MAIL SURFACE
+- account
+- thread / recipient
+- requested action
+
+DRAFT
+- subject
+- body
+
+STATUS
+- drafted / sent / blocked
+- proof of Sent when applicable
+
+NEXT STEP
+- send
+- follow up
+- archive / move
+```
+
+## Pitfalls
+
+- do not claim send success without a sent-copy check
+- do not ignore the thread history and write a contextless reply
+- do not mix mailbox work with DM or text-message workflows
+- do not expose secrets, auth details, or unnecessary message metadata
+
+## Verification
+
+- the response names the account and thread or recipient
+- any send claim includes Sent proof or an explicit client-side confirmation
+- the final state is one of drafted / sent / blocked / awaiting verification