Introducing a new way to review your PRs.

Read the announcement

affaan-m / ecc

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

View on GitHub

30 documents · Updated Nov 20, 2026

docs / agent-catalog-and-prompts

Agent catalog and prompts

ECC is a capability catalog for coding assistants. It combines reusable agent roles, on-demand skills, task contexts, and coding rules so an assistant can apply focused behavior for planning, building, review, research, and verification without repeating every instruction in each prompt.

Capability catalog

The catalog separates the assistant's role from the knowledge and limits that guide the role. Agents perform focused work. Skills supply task knowledge. Contexts set the current work mode. Rules set broad engineering limits. Commands provide user-facing entry points.

CapabilityPurposeTypical activation
AgentsDelegate a focused engineering responsibility to a specialized assistantExplicit delegation or a command workflow
SkillsLoad detailed knowledge or a multi-step playbook when it is relevantTask context, command, or agent need
ContextsSet the working mode, such as development, review, or researchCurrent kind of work
RulesApply standards and safety limits across matching workAlways-on or path-scoped guidance
CommandsGive the engineer a direct way to start a workflowUser invocation, often with a slash command

Native files are the main source for these capabilities. agent.yaml is an export surface that names models, skills, commands, and tags. Native agents, commands, and hooks remain authoritative in the repository (agent.yaml• L1-11, agent.yaml• L161-263).

References: README.md• L130-153 docs/SKILL-DEVELOPMENT-GUIDE.md• L20-47 agent.yaml• L1-11

Capability layers

The layers work together without having the same job. An assistant can use a role for execution, a skill for depth, a context for the current mode, and rules for limits.

Agent definitions

Agent definitions describe specialized assistants and the work that should activate them. Each definition gives the host a role, a trigger description, a permitted tool set, and a model choice. Its body then defines the expected behavior (agents/planner.md• L1-20).

The catalog covers planning, architecture, test-led work, code review, security review, build repair, end-to-end checks, documentation, refactoring, and stack-specific review. It also includes focused roles for documentation upkeep, live application evaluation, agent-output quality, harness improvement, open-source release preparation, and TypeScript, JavaScript, and GDScript review. The role catalog and its command relationships are explained in Agent roles and command surface.

Two specialized definitions show how the catalog extends into distinct quality concerns. e2e-runner protects critical user journeys through browser or mobile test execution, artifact capture, and flaky-test handling (agents/e2e-runner.md• L17-29, agents/e2e-runner.md• L60-83). rag-pipeline-reviewer checks retrieval quality, context grounding, production-shaped evaluation, and insufficient-context behavior without taking over answer-prompt design (agents/rag-pipeline-reviewer.md• L18-25, agents/rag-pipeline-reviewer.md• L35-54).

Reusable definitions also share a prompt-defense baseline. This protects role boundaries and sensitive data before role-specific instructions take effect (agents/e2e-runner.md• L8-16, agents/rag-pipeline-reviewer.md• L8-16, agents/bengali-reviewer.md• L8-16).

References: agents/planner.md• L1-20 agents/e2e-runner.md• L17-29 agents/e2e-runner.md• L60-83 agents/rag-pipeline-reviewer.md• L18-25 agents/rag-pipeline-reviewer.md• L35-54 agents/bengali-reviewer.md• L8-16 docs/COMMAND-AGENT-MAP.md• L5-29

Skill library

Skills are reusable knowledge modules. They give an assistant domain guidance, workflow steps, reference material, or decision support when the task needs that knowledge. Unlike an agent, a skill does not represent a separate worker (docs/SKILL-DEVELOPMENT-GUIDE.md• L20-45).

Curated skills cover software stacks, testing, security, research, operations, content work, and ECC workflows. Important capability groups include payment controls, context and decision records, documentation governance, issue review, module governance, and TypeScript patterns. The skill and rule library is described in Skills, contexts, and language rules.

References: docs/SKILL-DEVELOPMENT-GUIDE.md• L51-64 docs/SKILL-DEVELOPMENT-GUIDE.md• L107-115 skills/…/SKILL.md• L8-15 skills/…/SKILL.md• L7-22 skills/…/SKILL.md• L8-20 skills/…/SKILL.md• L8-31 skills/…/SKILL.md• L9-25 skills/…/SKILL.md• L8-19

Contexts and rules

Contexts give the assistant a small operating mode for the work in progress. The development context favors implementation and checks after a change. The review context favors careful reading and severity-based findings. The research context favors exploration before action (contexts/dev.md• L1-20, contexts/review.md• L1-22, contexts/research.md• L1-26).

Rules provide the stable floor beneath those modes. ECC installs language-independent rules from rules/common/ and can add language or framework packs. A specific pack extends the common layer and takes precedence when the two layers differ (rules/README.md• L5-33, rules/README.md• L128-145). Domain context is separate from work mode. The context-and-decisions skill keeps stable terms in the existing glossary and sends hard-to-reverse choices to the existing decision record workflow (skills/…/SKILL.md• L11-22, skills/…/SKILL.md• L36-45).

References: contexts/dev.md• L1-20 contexts/review.md• L1-22 contexts/research.md• L1-26 rules/README.md• L5-33 rules/README.md• L102-107 skills/…/SKILL.md• L11-22

Capability composition

An assistant starts with a user goal, enters through a command or direct request, and gains only the role, knowledge, mode, and limits needed for that work. This keeps the prompt focused while preserving a common engineering standard.

The following flow shows how the catalog turns a request into specialized assistant behavior.

flowchart LR
    A[User goal] --> B[Command or direct request]
    B --> C[Agent role]
    B --> D[Relevant skill]
    B --> E[Task context]
    C --> F[Specialized assistant behavior]
    D --> F
    E --> F
    R[Common and stack rules] --> F
    F --> G[Plan, change, review, or verified result]

The layers are selected by need instead of loaded as one undivided prompt. A planning request can use the planner role and planning knowledge. A review request can use a review role or command with security and stack rules. A repeated workflow can become a skill when it needs richer guidance than a rule should carry (docs/capability-surface-selection.md• L7-28).

References: docs/capability-surface-selection.md• L7-28 docs/SKILL-DEVELOPMENT-GUIDE.md• L39-47 docs/COMMAND-AGENT-MAP.md• L68-75

Catalog discovery and validation

ECC treats the catalog as a maintained product surface rather than an informal folder of prompts. Catalog checks count agent files, command files, and skill entry points, then compare those counts with tracked documentation and manifests (scripts/…/catalog.js• L18-25, scripts/…/catalog.js• L50-60).

Validation protects the contracts that let a host discover and use a capability:

The result is a catalog that can be inspected, selectively installed, and checked for drift as roles and guidance change.

References: scripts/…/catalog.js• L50-60 scripts/…/validate-agents.js• L63-119 scripts/…/validate-skills.js• L167-210 manifests/install-modules.json• L30-56 skills/…/SKILL.md• L45-88 skills/…/module_audit.py• L34-91

Host delivery and boundaries

ECC delivers the catalog through host-specific packages while keeping capability meaning consistent. Claude Code receives skills, agents, commands, and plugin-managed hooks. Other harnesses receive the surfaces their adapters support, so feature parity can differ by host (README.md• L146-157).

Installation is a selection decision. Profiles and modules group baseline capabilities with optional framework, security, research, workflow, and orchestration capabilities (manifests/install-profiles.json• L3-45). Users should choose one install method per harness because stacking methods can duplicate prompts, commands, hooks, or configuration (README.md• L267-280).

The Codex plugin points to the canonical root skill catalog instead of keeping a second copy. This preserves one source of truth while the plugin supplies the host-facing package boundary (plugins/…/README.md• L12-25). The Pi Core capability bundle follows the same catalog principle for its host-facing capability set. Its scope and delivery details are covered in Pi Core capability bundle.

References: README.md• L146-157 README.md• L267-280 manifests/install-profiles.json• L3-45 plugins/…/README.md• L12-25

Use Agent roles and command surface to follow role definitions into commands and engineering workflows. Use Skills, contexts, and language rules to compare reusable task knowledge with mode guidance and stack-specific limits. Use Pi Core capability bundle to understand the host-facing Pi Core capability set.

References: docs/COMMAND-AGENT-MAP.md• L5-29 docs/SKILL-DEVELOPMENT-GUIDE.md• L39-47 rules/README.md• L102-107 docs/pi-core-capability-bundle.md

Change checklist

When these files or sections are changed, remember to consider these:

  • When an agent is added, renamed, or removed, update host-facing command references and catalog expectations that use the agent count.
  • When an E2E or retrieval-review agent changes scope or output, keep its trigger description and handoffs aligned with the workflow that delegates to it.
  • When a skill changes its directory or entry-point name, keep the directory name, SKILL.md frontmatter name, install-module path, and export catalog aligned.
  • When a common rule changes, check language-specific extensions and their more-specific override behavior.
  • When a context or prompt changes, check that each supported host still receives the intended capability surface rather than a duplicate or unsupported copy.
  • When install modules or profiles change, preserve their dependency order so optional skills receive the baseline agents, commands, rules, and platform support they require.
  • When a skill creates or changes a context, glossary, review report, or module record, keep its existing owner and approval boundary intact rather than creating a parallel artifact.

Important failure modes

TriggerConsequenceGuard
An agent definition lacks model or tools, or uses an unsupported modelThe catalog fails validation and the host may not have a usable role definitionKeep required frontmatter fields and supported model names; run the agent validator
A retrieval-review agent accepts raw top-k context without relevance checks or production-path evaluationThe assistant can approve a noisy or weakly grounded RAG resultRequire reranking or relevance filtering, final-context checks, and faithfulness, context recall, and context precision evaluation
An E2E run uses replayed agent steps as proof of live stabilityFlaky behavior can remain hidden because the browser does not repeat the live agent actionsUse live runs without cache when checking flakiness and preserve failure artifacts
A catalog count or install path is not updated after a capability changeDocumentation or selection tools report stale coverage, or a selected module points at a missing capabilityReconcile catalog output and install-module paths with native files
A curated skill directory has no non-empty SKILL.mdThe skill is not discoverable as a catalog entryKeep the directory entry point and validate curated skills
A language rule pack is flattened over the common packOne file can overwrite another and relative links between layers can breakCopy common and language directories as separate layers
Two install methods are applied to one harnessThe harness can load duplicate skills, commands, hooks, or configurationChoose one install path per harness

Key files

FileWhy to read it
agent.yamlShows the export-level identity, model preference, and named skill and command surface while pointing back to native repository authority
agents/planner.mdShows the shape of a reusable agent definition and its role, tools, model, and prompt contract
agents/e2e-runner.mdShows the end-to-end testing role, browser and mobile flow coverage, artifact handling, and flaky-test controls
agents/rag-pipeline-reviewer.mdShows the retrieval review role, production-path evaluation focus, grounding checks, and review handoffs
agents/doc-updater.md, agents/agent-evaluator.md, agents/harness-optimizer.mdShow documentation, output-quality, and harness-improvement roles
agents/opensource-forker.md, agents/opensource-sanitizer.mdShow the clean staging and independent release-audit stages
skills/…/SKILL.md, skills/…/SKILL.mdShow how reusable skills preserve knowledge ownership and govern broad documentation work
contexts/dev.md, contexts/review.md, contexts/research.mdShow the compact work modes that frame assistant behavior
rules/README.mdExplains the common-plus-stack rule model and the relationship between rules and skills
scripts/…/catalog.js, scripts/…/validate-agents.js, scripts/…/validate-skills.jsDefine catalog discovery and the minimum discovery contracts for agents and curated skills
manifests/install-modules.json, manifests/install-profiles.jsonShow how hosts and user profiles select baseline and optional capability groups
docs/COMMAND-AGENT-MAP.mdMaps user commands to agents, skills, and runtime workflows