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 / skills-contexts-and-language-rules

Skills, contexts, and language rules

ECC uses three guidance layers to shape agent work: skills provide reusable workflows and domain knowledge, contexts set the mode for a task, and rules set durable standards for a language or framework. Together they let an agent load focused help for the work at hand without placing every workflow in every session.

This page is a child of Agent catalog and prompts and complements Agent roles and command surface and Pi core capability bundle, which cover the workers, entry points, and shared capability set that consume this guidance.

Guidance model

The guidance model separates reusable knowledge from task mode and required standards. A skill helps an agent perform a kind of work. A context tells it how to approach the current phase. A rule states what must remain true while it works.

This diagram shows how the request and project stack select guidance before the agent produces an engineering result.

flowchart LR
    Request[Engineering request] --> Mode[Task context]
    Request --> Skill[Relevant skill]
    Project[Project stack] --> Rules[Language or framework rules]
    Mode --> Agent[Agent behavior]
    Skill --> Agent
    Rules --> Agent
    Agent --> Result[Focused engineering result]

These layers are related but are not substitutes. Skills are normally selected for a task. Contexts can change between development, review, and research. Rules stay in force for the scope where they are installed. This separation controls behavior quality and context size.

References: README.md• L912-922 manifests/install-components.json• L5-11

Skill library

The skill library is the reusable knowledge layer for engineering work. Each skill describes when it applies and then gives the agent a focused workflow, pattern set, or domain guide instead of a general instruction dump.

Skill activation

Skills use trigger-first descriptions to connect user intent with the right guidance. A framework skill narrows advice to a stack. A workflow skill narrows advice to a kind of change. The agent should prefer the narrowest relevant skill and combine it with a broader workflow skill only when the task needs both.

Some skills constrain the work before it starts. GateGuard turns investigation into a precondition for edits and new files. It asks for facts about callers, public behavior, data, or the instruction that governs the change. The first attempt can be denied until those facts are available. This is different from self-evaluation because the investigation itself supplies working context.

Other skills constrain the point at which work may finish. config-health gives soft warnings about rule and hook drift during a session. delivery-gate provides a hard stop at session end. safety-guard remains advisory unless the host adds a blocking permission or hook. These skills improve control, but none grants permission to perform an external or destructive action.

References: skills/…/SKILL.md• L8-31 skills/…/SKILL.md• L191-219 skills/…/SKILL.md• L8-26 skills/…/SKILL.md• L48-60

Domain guidance

The library covers both common engineering work and high-impact work. Its main purpose is to make the boundary of an action clear before an agent treats a plan, draft, test result, or provider response as authority.

DomainGuidance goal
Agent operation and evaluationMake autonomous operation explicit and measure behavior before it is trusted or changed.
Agent harness designShape tools, observations, recovery paths, and context use so work can reach a checked result.
Engineering delivery and qualityTurn design, implementation, migration, performance, localization, and verification into bounded changes with evidence.
Language and framework stacksApply reusable patterns for web, backend, data, infrastructure, game, and platform work.
Accessible interface designKeep web and mobile interfaces usable with assistive technology through semantic structure, clear focus, labels, and visible status.
Human interface reviewLet a human adjust a local UI preview before the agent ports the approved result into production code.
External systems and paid servicesSeparate discovery, validation, approval, payment, publishing, and execution authority.
Research and dataUse named sources and repeatable searches while separating retrieved facts from analysis.
Creative and media workKeep local plans and review evidence distinct from provider generation and live delivery.

Engineering workflow skills provide a shared boundary for code changes. Intent-driven development turns ambiguous work into observable acceptance criteria. TDD keeps requirements, a failing check, the smallest passing change, and later refactoring in one loop. Database migration guidance separates schema work from data work and treats production changes as durable, reviewable history. Browser and canary skills separate pre-release checks from post-deploy monitoring.

Stack skills add the domain model needed to make a change safely. Django-Celery guidance treats background work as retryable and potentially duplicated. Godot guidance keeps game rules testable outside scene nodes and pairs with headless or scene-level checks. Kubernetes, Terraform, and Platform Factory guidance treat deployment state, resources, locks, evidence, and release actions as controlled boundaries. Rails security guidance implements the choices in the Ruby security rules rather than replacing them.

The library also covers agent harness design, accessible interfaces, and visual UI approval. Agent harness guidance separates action selection from observation and recovery, accessibility guidance maps interface meaning to the needs of assistive technology across web and mobile, and UI Canvas keeps a local human-edited preview separate from production code. These skills add task guidance without becoming authority for a live or destructive action.

Specialized skills extend the same model to Blender motion inspection, Yoruba localization, web-perimeter audits, scientific search, market research, data scraping, short-video distribution, and reverse engineering. These guides distinguish observable evidence from inference and keep user approval over live or high-impact actions.

References: skills/…/SKILL.md• L6-30 skills/…/SKILL.md• L41-84 skills/…/SKILL.md• L20-38 skills/…/SKILL.md• L201-205 skills/…/SKILL.md• L19-25 skills/…/SKILL.md• L21-45 skills/…/SKILL.md• L7-22 skills/…/SKILL.md• L8-25 skills/…/SKILL.md• L8-19 skills/…/SKILL.md• L9-19 skills/…/SKILL.md• L20-30 skills/…/SKILL.md• L20-35

External effects

Skills for payments, publishing, research, and operational tools keep a local result separate from an external effect. The distinction matters because a successful draft, dry run, or local test does not prove that a message was sent, a payment settled, a workload launched, or a release was accepted.

For x402 payments, the agent-payment skill supports buyer and seller paths across supported EVM and Solana networks. The orchestrator owns budgets, approved origins, recipients, assets, networks, and human confirmation. Seller guidance also requires a durable claim before paid handler side effects so one authorization cannot run the work many times. Roundhouse is one optional discovery index or hosted facilitator, not the source of spending authority.

For social and media work, the distribution path validates the file and platform-specific metadata first. It then shows the exact privacy, disclosure, caption, and schedule choices for approval before publishing. Returned platform content and provider responses remain data, not instructions.

References: skills/…/SKILL.md• L38-57 skills/…/SKILL.md• L105-116 skills/…/SKILL.md• L309-459 skills/…/SKILL.md• L10-25 skills/…/SKILL.md• L25-41 skills/…/SKILL.md• L72-103

Skill lifecycle

Skills are treated as reusable assets that can be found, installed, checked, measured, and improved. Skill Scout searches existing sources before a new skill is created. Skill Stocktake checks the live library for changes and overlap. Skill Comply measures whether agents follow a skill or rule under supportive, neutral, and competing prompts.

The compliance path is evidence-oriented. It generates a behavioral specification, runs isolated scenarios, captures tool timelines, classifies actions, and checks ordering separately from model judgment. Its sandbox is a fixture boundary with simulated GitHub behavior; a passing report does not prove a real pull request, merge, or hosted check.

Benchmark optimization uses the same discipline for measured improvement. It defines the user outcome, freezes the metric and expected results, establishes a baseline, tests one hypothesis per variant, records failures and cost, and promotes only the best measured admissible result. A faster result is not accepted if correctness or another hard constraint fails.

References: skills/…/SKILL.md• L28-105 skills/…/scan.sh• L37-45 skills/…/scan.sh• L96-159 skills/…/quick-diff.sh• L37-59 skills/…/SKILL.md• L9-17 skills/…/run.py• L94-177 skills/…/runner.py• L81-139 skills/…/SKILL.md• L30-83 skills/…/SKILL.md• L127-143 skills/…/sources.md• L3-13

The continuous-learning system forms a second lifecycle for reusable guidance. It observes session activity, extracts small evidence-backed instincts, and keeps project behavior separate from global behavior. Repeated evidence across projects can support promotion to global scope, while unreviewed pending instincts expire. The older continuous-learning skill is retained for compatibility but directs new work to continuous-learning-v2.

Project identity can come from an explicit project directory, a normalized Git remote, or a repository path. Observation hooks use the validated working directory and record bounded, scrubbed tool data. Automated observer sessions are excluded so the learning system does not learn from its own analysis. Detection keeps project records in project-scoped storage and can reuse a safe daily cache without changing the selected project when repository identity changes.

References: skills/…/SKILL.md• L9-24 skills/…/SKILL.md• L127-150 skills/…/SKILL.md• L294-328 skills/…/instinct-cli.py• L306-425 skills/…/instinct-cli.py• L719-751 skills/…/observe.sh• L98-117 skills/…/observe.sh• L377-409 skills/…/observe.sh• L514-590 skills/…/detect-project.sh• L113-269 skills/…/detect-project.sh• L343-375 skills/…/SKILL.md• L1-13 skills/…/config.json• L1-19

Shared context and handoffs

unified-memory provides portable context for recall, handoff, and resume work across harnesses. ck provides a separate project-session continuity path for Claude Code. It registers projects, stores structured context and session summaries, renders a human-readable view, and injects a compact brief at session start.

The ck flow keeps project identity, goal, constraints, last stopping point, next steps, decisions, blockers, and recent Git activity together. Session start can warn about an unsaved prior session or a mismatch between the saved goal and CLAUDE.md. Saving updates the structured record, its generated view, and a native memory entry. Migration carries older markdown and metadata into the current structured format, preserves a backup of the old metadata, and skips already valid current contexts.

Memory recall and session context are evidence rather than authority. Agents must bind searches to the workspace and allowed scopes, check important claims against current sources, and keep recalled text separate from executable instructions. ck state must be changed through its commands rather than by editing its structured source or generated view directly.

References: skills/…/SKILL.md• L8-19 skills/…/SKILL.md• L58-103 skills/…/init.mjs• L15-27 skills/…/migrate.mjs• L94-131 skills/…/migrate.mjs• L135-225 skills/…/save.mjs• L142-176 skills/…/save.mjs• L178-224 skills/…/shared.mjs• L60-79 skills/…/session-start.mjs• L103-179

Task contexts

Task contexts are short mode prompts for changing the agent’s working posture without changing the project’s durable standards. The repository defines development, review, and research modes under contexts/.

Context modes

Each context emphasizes a different phase of engineering work:

ContextPrimary aimTypical behavior
DevelopmentMove from intent to a working changeEdit, build, and test in short cycles
ReviewFind and explain risks in existing changesRead first, rank findings, and suggest fixes
ResearchBuild a sound understanding before actingExplore, verify, and summarize before writing code

The common review rule makes review a normal part of delivery. It applies after code changes, before commits to shared branches, before merges, and whenever security-sensitive or architectural code changes. It also routes authentication, user input, data access, external calls, cryptography, and payment work to security review.

References: contexts/dev.md• L1-20 contexts/review.md• L1-22 contexts/research.md• L1-26 rules/…/code-review.md• L7-23 rules/…/code-review.md• L39-82

Context economy

ECC aims to keep task context small and purposeful. Skills are loaded when their triggers match the task. Rules are always-loaded guidance and must be selected with care. The context-budget skill inventories guidance and tool overhead so teams can reduce waste before adding more components.

Strategic compaction preserves files, instructions, memory, and Git state, but not the working conversation or tool history. The agent must write the plan and other needed handoff state to a durable file before compaction. Iterative retrieval adds code context in passes instead of sending everything at once.

References: skills/…/SKILL.md• L8-18 skills/…/SKILL.md• L20-118 skills/…/SKILL.md• L20-39 skills/…/SKILL.md• L89-121 skills/…/SKILL.md• L20-34

Language and framework rules

Language and framework rules are durable standards that constrain code across a project or harness. They turn stack choice into explicit guidance for style, patterns, testing, security, and related concerns.

Rule layering

The rules library has a shared rules/common/ layer and stack-specific directories such as rules/typescript/, rules/python/, rules/vue/, and rules/ruby/. A stack pack extends the common layer rather than replacing it. File path patterns decide which files receive a rule pack, so one pack can cover more than one related file type.

The common layer sets the floor for immutable data, simple design, focused files, explicit errors, boundary validation, and clear names. It also defines review, delegation, hook, model, context, performance, and build-recovery expectations. The current review standard uses a severity model and treats critical security or data-loss risk as a merge block. Stack rules then add the conventions that only make sense for a language or framework.

Ruby rules show the relationship clearly. rules/…/security.md selects Ruby and Rails paths and extends common security guidance with CSRF, strong parameters, safe queries, session rotation, recovery controls, dependency checks, output escaping, and untrusted job or webhook boundaries. rails-security supplies task-time patterns for those decisions; it does not replace the durable rule layer.

References: rules/…/coding-style.md• L3-13 rules/…/coding-style.md• L15-63 rules/…/code-review.md• L25-59 rules/…/agents.md• L3-23 rules/…/hooks.md• L3-15 rules/…/security.md• L1-24 rules/…/security.md• L26-51 skills/…/SKILL.md• L7-22

Stack selection

Install selection connects a project’s stack to the rules and skills that support it. The component catalog distinguishes language components such as lang:typescript and lang:python from framework components such as framework:react, framework:vue, and framework:angular. Most selections resolve through shared framework-language modules, while specialized stacks can add security or platform modules.

The usual choice is the common rules plus only the language and framework packs used by the project. This avoids conflicting advice and reduces always-loaded context. Framework skills add task-time workflow guidance without replacing durable rules. The same model applies to newer stack guides for Godot, Terraform, Kubernetes, and platform builds: select them because the task matches the stack, then keep project-specific policy and release authority in their proper systems.

References: manifests/install-components.json• L53-140 manifests/install-modules.json• L148-243 manifests/install-profiles.json• L33-45 README.md• L198-208 rules/…/testing.md• L1-46 rules/…/coding-style.md• L1-20 skills/…/SKILL.md• L7-25 skills/…/SKILL.md• L8-21 skills/…/SKILL.md• L8-19

Guidance flow

When an agent receives engineering work, the guidance layers work together in a simple sequence:

  1. Identify the task mode: development, review, or research.
  2. Match the project’s language and framework to the relevant rule packs.
  3. Activate skills whose descriptions match the requested workflow or domain.
  4. Complete any required pre-action investigation before editing or creating files.
  5. Add only the code and task context needed for the current phase.
  6. Produce the result under the selected rules and preserve useful outcomes for later work.

This sequence is especially important for changes with a data, payment, deployment, or external communication boundary. It keeps acceptance evidence, benchmark evidence, review findings, provider results, and user authority separate. The host may record bounded skill identifiers, versions, and outcomes for health reporting, but skill telemetry is not a copy of prompt text.

References: skills/…/SKILL.md• L56-85 skills/…/SKILL.md• L63-71 skills/…/SKILL.md• L21-90 skills/…/SKILL.md• L239-271 skills/…/SKILL.md• L47-90 scripts/…/skill-run-tracker.js• L4-20 scripts/…/skill-run-tracker.js• L123-146

Change checklist

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

  • Update the related install component and module when a skill or rule pack changes its scope or dependencies.
  • Keep a skill’s activation description aligned with its actual subject so on-demand loading does not select the wrong guidance.
  • Preserve the common-to-stack rule relationship when adding or moving language and framework standards.
  • Check relative links when moving namespaced rules or skills because installed paths can differ.
  • Reassess context cost when adding always-loaded rules or broadening a default install profile.
  • Keep pre-action gates aligned with the tools and facts that the agent must inspect before a change.
  • Keep context, contract, decision, impact, and documentation ownership linked rather than creating parallel sources.
  • Keep benchmark baselines, correctness gates, failure accounting, and promotion limits aligned when performance guidance changes.
  • Keep migration examples aligned with the schema contract, lock behavior, backfill order, and rollback path they describe.
  • Keep background-task guidance aligned with publish-after-commit, acknowledgement, retry, idempotency, and overlap boundaries.
  • Keep payment policy checks bound to server-provided network, asset, recipient, amount, and approved resource origins before signing.
  • Keep seller replay claims durable long enough for authorization expiry and before handler side effects.
  • Keep project-scoped learning separate from global learning, and preserve validation, deduplication, expiry, and promotion boundaries.
  • Keep observation project selection bound to a validated hook path and keep project identity changes from reusing the wrong cache or data store.
  • Keep ck command state, migration backups, generated context views, session-start injection, and native memory entries consistent.
  • Keep skill-comply generation, trace parsing, temporal grading, sandbox limits, and report boundaries aligned.
  • Keep external publishing guidance tied to exact approved content, target accounts, schedule, and delivery evidence.
  • Keep browser QA read-only by default and keep post-deploy canary checks separate from pre-deploy visual and interaction checks.
  • Keep language-specific rules aligned with the common agent, hook, performance, and review standards they extend.
  • Keep accessibility guidance aligned across semantic roles, focus behavior, labels, status announcements, and target-size expectations.
  • Keep UI Canvas exports treated as review input, not as production artifacts, and preserve the link between human feedback and the component that receives it.
  • Keep security and testing skill triggers aligned with the stack behavior they claim to guide.
  • Keep Terraform plan/apply approval and Platform Factory freeze/verify gates distinct from release execution authority.

Important failure modes

TriggerConsequenceGuard
Install every language or framework pack by defaultAlways-loaded guidance grows and can conflict across stacksStart with common rules and the project’s active stack only
A skill description does not match its workflowThe agent loads guidance at the wrong time or misses a needed skillKeep descriptions trigger-first and review them with stocktake
A stack pack omits the common rule layerShared safety and quality standards are lostTreat stack rules as extensions of rules/common/
A first edit skips GateGuard factsCallers, contracts, or data shape can be guessed instead of checkedInvestigate first and retry after presenting the requested facts
Code review is skipped after a sensitive changeA security or data-loss issue can reach a merge gateUse the review context and route sensitive work to security review
A benchmark variant lowers the evaluator or skips failuresA fast result can be wrong or impossible to reproduceFreeze expected results, retain failures, and promote only an admissible winner
A migration mixes schema and data work or edits a deployed migrationEnvironments drift and rollback becomes unclearUse immutable forward migrations and separate backfills
A task is published inside an uncommitted database transactionA worker can run before rows exist or after the transaction rolls backPublish after commit and use an outbox when atomic delivery is required
An x402 client trusts a server challenge for origin, asset, recipient, or budgetThe agent can sign an unexpected paymentFilter every challenge through orchestrator policy and require confirmation
An x402 seller runs the handler before claiming an authorizationReplays can repeat paid side effectsClaim once in durable storage after verification and before the handler
Project instincts are loaded as global guidance without reviewLocal habits can affect unrelated projectsKeep scope in the record and require repeated evidence before promotion
Observation input is not validated before project detectionData can attach to the wrong project or the global scopeAccept only an absolute existing hook path and re-check repository identity
A ck session starts with stale or unsaved stateThe agent can continue from a wrong goal or lose the handoffUse the command path and read session-start warnings
A ck v1 context is treated as a current v2 context without migrationSession data can be unreadable or updates can stopRun migration and retain the old metadata backup
A persisted byte count is treated as active context useCapacity or billing decisions become falseUse the harness’s current context and usage signals
Skill compliance uses a real GitHub or external environmentThe report can be mistaken for proof of a live integrationTreat the sandbox and simulated provider boundary as explicit
A browser QA run performs a mutating journey against productionReal accounts or data can changeUse test credentials and staging with explicit opt-in
A UI Canvas pending edit is copied into the mockup before an export eventThe same human change can be applied twice or in the wrong placeApply only exported edit or finish payloads and acknowledge the batch
A Terraform plan is applied without human review or a saved planInfrastructure can change beyond the reviewed intentReview the saved plan before apply
Platform Factory builds after a dependency change without freezingThe image and evidence can use stale dependency stateFreeze, build, verify, then use the authorized release path
A moved skill or rule keeps old linksInstalled documentation points to a missing or wrong targetUpdate namespaced links and verify the install link index

Key files

FileWhy to read it
README.mdGives the system-level distinction between skills, rules, agents, hooks, and instincts.
manifests/install-components.jsonMaps language, framework, capability, and individual skill choices to install modules.
manifests/install-modules.jsonDefines reusable groups of rules and skills plus their targets and dependencies.
manifests/install-profiles.jsonShows how small and broad installation profiles compose the guidance catalog.
contexts/dev.md, contexts/review.md, contexts/research.mdDefine the three main task modes.
rules/…/coding-style.md, rules/…/code-review.mdDefine the shared quality floor and review gate.
rules/…/security.md, skills/…/SKILL.mdShow how durable Ruby rules and task-time Rails guidance work together.
skills/…/SKILL.md, skills/…/SKILL.mdShow pre-action investigation and soft configuration health monitoring.
skills/…/SKILL.md, skills/…/SKILL.mdShow how ambiguous work becomes acceptance evidence and how code moves through RED, GREEN, and refactor stages.
skills/…/SKILL.mdDefines the action, observation, recovery, context, and verification concerns for agent tooling.
skills/…/SKILL.mdDefines cross-platform interface guidance for assistive technology and WCAG 2.2 AA work.
skills/…/SKILL.mdDefines the local human-editable preview loop for visual UI changes.
skills/…/SKILL.md, skills/…/SKILL.mdShow how reusable guidance is measured for performance and behavioral compliance.
skills/…/SKILL.md, skills/…/instinct-cli.py, skills/…/observe.sh, skills/…/detect-project.shDefine project-scoped learning, promotion, observation, project identity, and privacy boundaries.
skills/…/shared.mjs, skills/…/migrate.mjs, skills/…/save.mjs, skills/…/session-start.mjsShow how project context is migrated, saved, and turned into a compact start-of-session brief.
skills/…/SKILL.md, skills/…/SKILL.mdDefine payment authority, replay boundaries, discovery, and facilitator choices.
skills/…/SKILL.md, skills/…/postgres-column-rename.sqlDefine safe schema change and zero-downtime migration goals.
skills/…/SKILL.md, skills/…/reliability.mdDefine asynchronous delivery, retries, acknowledgement, and transaction boundaries.
skills/…/SKILL.md, skills/…/SKILL.mdSeparate pre-deploy user checks from post-deploy health monitoring.
skills/…/SKILL.md, skills/…/SKILL.md, skills/…/SKILL.mdShow how build evidence, cluster operation, and infrastructure changes retain safety gates.
skills/…/SKILL.md, skills/…/SKILL.mdShow evidence-first guidance for language quality and public web security surfaces.
skills/…/scan.sh, skills/…/quick-diff.shShow how the live skill library and changed skill files are inventoried.