ECC · Analysis for IKA Concierge

Posture: harness-native operator system for agentic coding work, distributed as an NPM/marketplace install across seven AI coding harnesses. MIT-licensed. Single maintainer, weekly cadence, ~150 GitHub App installs at clone time.

Stack: JavaScript/TypeScript for the hook runtime, Python for the dashboard + LLM core (src/llm/ with provider abstractions over Ollama / AstraFlow / Claude / OpenAI), Rust prototype for an out-of-process control plane (ecc2/), shell installers.

Distribution: ecc-universal + ecc-agentshield NPM packages; ecc-tools GitHub App; gitagent agent.yaml spec; per-harness manifest shells (.claude-plugin/, .codex-plugin/, .opencode/, .cursor/, .kiro/, .gemini/, .qwen/, .zed/, .codebuddy/, .trae/).

Repo shape:

• agents/ — 64 markdown specialist subagent definitions (planner, code-reviewer, security-reviewer, language-specific reviewers + build-resolvers, harness-optimizer, loop-operator…)
• skills/ — 261 directories, each SKILL.md with YAML frontmatter (name, description, origin)
• commands/ — 84 legacy slash-command shims (now deprecated by ECC themselves; skills-first)
• hooks/hooks.json — ~25 lifecycle hooks wired to dispatcher scripts
• rules/ — common + per-language always-on guidelines
• mcp-configs/ — 14 MCP server configurations
• ecc2/ — Rust control-plane prototype with SQLite state store; CLI dashboard / start / sessions / status / stop / resume / daemon
• src/llm/ — Python LLM core with pluggable providers

Design choices worth naming:

• Runtime hook gating via env vars — ECC_HOOK_PROFILE=minimal|standard|strict and ECC_DISABLED_HOOKS=... let an operator turn hooks down without editing files. Graceful degradation, not all-or-nothing.
• Consolidated dispatchers — pre:bash:dispatcher and post:bash:dispatcher route through one preflight/postflight script each, instead of N separate hook entries. Faster cold start, easier to reason about ordering.
• Lifecycle event coverage — PreToolUse, PostToolUse, PreCompact, SessionStart, Stop, SessionEnd, PostToolUseFailure. Hook contract is wider than what IKA's Superpowers adoption (v25.12) currently uses.
• Instincts as the unit of learning — atomic (one trigger, one action), confidence-weighted (0.3–0.9), domain-tagged, evidence-backed, project-scoped (v2.1) with a promote-to-global rule when seen in 2+ projects. Sits cleanly below Skills (instinct → cluster → skill/command/agent).
• Iterative retrieval as a named pattern — 4-phase loop (DISPATCH → EVALUATE → REFINE → LOOP, max 3 cycles) packaged as a skill so it's referenceable from any agent prompt.
• Context budget as a first-class audit surface — a skill that estimates token overhead per loaded component (agents/skills/rules/MCP/CLAUDE.md), classifies into Always/Sometimes/Rarely needed, flags bloat patterns, produces a savings report.
• Fact-force gate — pre:edit-write:gateguard-fact-force blocks the FIRST Edit/Write per file per session until the agent has demonstrably investigated (importers, schemas, user instructions). Cuts the "agent edited the file without reading the file it depends on" failure mode.
• Config-protection — refuses edits to lint/format config files so the agent has to fix the code, not weaken the linter. A specific instance of the broader "agent steering" pattern.

E1 · Hook profile env-var

Pattern: ECC_HOOK_PROFILE=minimal|standard|strict + ECC_DISABLED_HOOKS=<id>,<id> let an operator turn the hook pipeline down without editing files. Each hook declares which profiles it runs under (e.g. minimal,standard,strict for the metrics bridge; standard,strict for stricter gates).

Why now: IKA shipped the SessionStart hook contract in v25.12. There is no runtime kill-switch yet — a misbehaving hook has to be deleted from skill_hooks, which means a migration. Adding a min_profile column and reading an env var at the dispatcher is ~50 lines and gives us a graceful degradation path for incidents.

IKA integration: extend the skill_hooks table from v25.12 with min_profile TEXT NOT NULL DEFAULT 'standard'. Read IKA_HOOK_PROFILE (default standard) and IKA_DISABLED_HOOKS (comma list of hook ids) in the dispatcher. No new entity, no schema-per-IKA work — global infrastructure.

Effort: ~½ day.

E2 · GateGuard fact-force

Pattern: a PreToolUse hook on Edit/Write that blocks the FIRST modification per file per session until the agent has demonstrably investigated the file's context (importers, schema references, user instructions referencing it). Subsequent edits to the same file in the same session pass without the gate.

Why now: the most common Conversation-Surface failure mode is "IKA wrote the field, but the field doesn't exist in the schema" or "IKA updated the contact name, but the contact lives in a different IKA". A write-time gate that forces a read first turns this from a silent failure into a deliberate investigation. Pairs with superpowers/verification-before-completion, which fires at done-time — fact-force fires at write-time, so the two together bracket every operation.

IKA integration: new PreToolUse hook on Operations Edit / Write tool calls. Track (conversation_id, entity_type, entity_id) "investigated" flags in conversation state. Skip the gate when the user explicitly asked for the change ("agent-initiated" vs "user-explicit" distinction).

Effort: ~1 day including the user-vs-agent classifier wired to the existing conversation-surface classifier gate (v22).

E3 · Context-budget audit as a Skill

Pattern: a skill that scans every loaded component (agents, skills, rules, MCP servers, CLAUDE.md), estimates token overhead (words × 1.3), classifies into Always / Sometimes / Rarely needed, flags bloat (descriptions >30 words, files >200 lines, MCPs wrapping native CLIs, >10 servers, redundant content), and emits a prioritized savings report.

Why now: we are going to land in the exact same trap ECC hit. Once we have 30+ per-neuron Skills, 12+ MCP integrations, 8+ hooks installed across templates, the question "why is the Conversation Surface slow today?" becomes unanswerable without instrumentation. Building the audit as a first-class skill — and surfacing it both as /context-budget and as a chip in MyPanel — turns the question into a one-click answer.

IKA integration: add IKA-curated/context-budget skill backed by a SQL view over neuron_skills / neuron_commands / neuron_plugins / neuron_integrations. Token estimate uses the same words × 1.3 heuristic ECC uses (no need for the actual tokenizer in the audit path). Per-IKA report stored as an Artifact in the Engineering neuron.

Effort: ~1 day.

E4 · Instincts — atomic confidence-weighted learned behaviors

Pattern (the most original idea in the repo): an instinct is a small learned behavior with shape { id, trigger, action, confidence: 0.3–0.9, domain, scope: project|global, evidence: [] }. Observations come in via the hook pipeline; a background Haiku agent (not the main context) clusters and writes instincts. Confidence decays without reinforcement. Project-scoped by default (keyed off git remote URL hash) so behaviors don't leak between projects. Promotion path: an instinct seen in 2+ projects gets promoted to global. Evolution path: instincts → cluster → Skill / Command / Agent.

Why this matters most: IKA already has the dream-cycle (gbrain lift #5) writing assessments — claims about the world. We do not have a place for claims about IKA's own behavior ("when Mats asks for a brief he means morning + Spanish + ≤10 bullets"). Instincts fill that gap with a primitive that is small enough to write automatically, confidence-weighted so the system knows what to trust, and scoped so multi-IKA isolation holds. It sits naturally between Notes (raw, free-form) and Skills (formal, vetted).

IKA integration:

• New instincts table per IKA (schema-per-IKA, fits the RLS floor).
• Scope key: instead of git remote URL hash, use (ika_id, neuron_id) with a scope: neuron | ika | global ladder. Promotion: neuron → ika when seen in 2+ neurons of the same IKA; ika → global when seen in 2+ IKAs of the same user.
• Observation source: ride the dream-cycle on its existing per-IKA cadence; do not run a background Haiku agent per-turn (out of posture for our cost model).
• Evolution path: a clustered instinct above confidence 0.85 with ≥5 evidence rows surfaces as a "promote to Skill" suggestion in the Engineering neuron, using the existing skill-creator pipeline.
• Disjointness with assessments: assessments.subject_type IN ('world', 'self') — keep one storage substrate but partition the index. Decision deferred until the migration is written; see Open questions.

Effort: ~3 days (schema + dream-cycle observer + promotion ladder + skill-promotion surface). Highest-leverage adopt on the page.

E5 · In-conversation cost / context monitor

Pattern: post:ecc-context-monitor injects a structured warning into the agent's next system turn when token cost, context-window utilization, or tool-loop heuristics cross thresholds. The agent self-corrects mid-turn instead of getting hard-stopped by the cap.

Why now: the per-IKA cost cap (in the token-stack section of /ika-pro-architecture) enforces at the budget layer — it kills the request when the cap is breached. The agent has no opportunity to wind down gracefully (write a partial result, defer to a cheaper model, ask the user). Adding the warning-injection pattern at 80% of cap / 70% of context window / 3 consecutive same-tool calls gives the agent a chance to land softly.

IKA integration: wire into the existing per-IKA cost-cap primitive. Emit a structured {type: "cost_warning", budget_remaining_pct, context_used_pct, recent_tool_repeat_count} block into the next system turn. Threshold tunable per-IKA in Settings → Conversation, defaults named above.

Effort: ~½ day.

E6 · Status as portable markdown handoff

Pattern: ecc status --markdown --write status.md produces a portable snapshot covering readiness, active sessions, skill-run health, install health, pending governance events, linked work items. Designed for cross-channel handoff (paste into Slack, email, etc.).

Why now: the Conversation Surface morning brief is already exactly this shape, but it lives only in the IKA thread. Making it emit a markdown variant lets Mats forward "what IKA is on today" into any channel without screenshots. Also lights up the IKA-as-collaborator surface for users who live in Slack/email more than in the IKA chrome.

IKA integration: existing Brief generator gains a format: markdown output path; same data, different serializer. Add an "Export" affordance on every Brief that copies the markdown or pipes it to a configured channel (Slack webhook, email, WhatsApp via per-neuron Integration).

Effort: ~½ day.

E7 · Safety-Guard freeze mode for autonomous runs

Pattern: lock all writes to a specific directory tree for the duration of an autonomous run. Any out-of-scope write is blocked with an explanation; reads remain unrestricted.

Why now: an Automation that runs under an agent identity should not, by default, be allowed to mutate the entire IKA. Today the bound is the per-Automation role/permissions, which is correct for ACL but not enforced at the write-tool layer. Adding a write_scope_path field that the PreToolUse hook checks against every Operations write turns "in theory the agent only touches Engineering" into "in fact the agent cannot touch anything else, even if the prompt convinces it to."

IKA integration: new automations.write_scope_path TEXT NULL; when set, every write tool call from the Automation's agent is checked against it. Out-of-scope = blocked at the hook with an explanation, audited to the per-IKA security log.

Effort: ~½ day.

1. Instinct vs assessment overlap. Both are typed claims with provenance. Decision needed: one table with a subject_type IN ('world', 'self') discriminator, or two tables with a shared evidence join? The choice constrains the dream-cycle observer code. Lean: one table, two indexes, two views.
2. Fact-force friction in a Conversation Surface. The pattern is borrowed from a coding harness where deliberate writes are the norm. In Concierge, the user expects "add a task called X" to land in one beat. Mitigation: only fire fact-force when the write is agent-initiated (planner / automation / suggestion) — never when the user issued an explicit command. Need to confirm the classifier-gate (v22) reliably distinguishes the two.
3. Hook profile interaction with Superpowers always_on. v25.12 added always_on BOOL on neuron_skills. Don't ship two parallel disable mechanisms — the new min_profile column should compose with always_on: a hook only runs if (always_on OR profile ≥ min_profile) AND NOT disabled.
4. Star count credibility. README claims "182K+ stars" in a markdown badge, but the live shields.io badge above does not corroborate that count. The technical patterns stand on their own merit — this matters only if the board narrative leans on social proof. Use the patterns, not the marketing.
5. License attribution. MIT, clean to vendor. Per-skill attribution row in the IKA-curated vetting tier is sufficient.

All paths relative to a fresh clone of github.com/affaan-m/ECC on 2026-06-09.

• README.md — top-of-funnel positioning, version history, package surface
• AGENTS.md — agent inventory + orchestration philosophy
• SOUL.md — core identity statement
• agent.yaml — gitagent spec surface (157 skills, 84 commands at this version)
• hooks/hooks.json — ~25 hook definitions across PreToolUse / PostToolUse / PreCompact / SessionStart / Stop / SessionEnd / PostToolUseFailure
• skills/continuous-learning-v2/SKILL.md — instinct model (v2.1 project scoping)
• skills/iterative-retrieval/SKILL.md — 4-phase subagent retrieval loop
• skills/context-budget/SKILL.md — token overhead audit + savings report
• skills/safety-guard/SKILL.md — Careful / Freeze / Guard modes
• src/llm/providers/ — Ollama / AstraFlow / Claude / OpenAI provider abstractions (confirms multi-provider posture)
• ecc2/ — Rust control-plane prototype with SQLite state store

Raw analysis notes: /tmp/ecc-analysis.md.