Agent Standards

Expert Instruction

Overview

Foundational meta-skill that defines behavioral and cognitive standards for senior AI engineering agents. Establishes the reasoning pipeline, memory architecture, and context engineering practices that enable autonomous, long-horizon task execution with verifiable outcomes.

When to use: Configuring agent reasoning, managing context windows, establishing verification protocols, orchestrating multi-agent workflows, optimizing token usage.

When NOT to use: Domain-specific coding tasks (use specialized skills), UI/UX design, database schema work.

Quick Reference

Common Mistakes

Delegation

• Explore a codebase to map framework versions and active patterns: Use Explore agent
• Execute a complex multi-step implementation with atomic commits: Use Task agent
• Plan architecture for a long-horizon feature with dependency analysis: Use Plan agent

References

• Cognitive architecture, reasoning stack, multi-agent orchestration, and cognitive load management
• Tiered memory systems, short-term to long-term persistence, and shared memory
• Agent communication protocols including MCP, A2A, and ACP standards
• Context engineering, token optimization, information hierarchy, and structured packing

Agent Protocols

Model Context Protocol (MCP)

The industry standard for agent-tool communication:

• Core: Universal framework for tools, resources, and prompts
• Advantage: Prevents vendor lock-in and allows agents to discover new capabilities dynamically
• Transport: JSON-RPC over Stdio (local) or SSE (remote)

Agent-to-Agent (A2A)

Peer-to-peer collaboration between specialized agents:

• Negotiation: Agents can bid on tasks based on their specialized skills
• Handoff: Passing context and mission objectives from one agent to another (Architect to Engineer, Engineer to Reviewer)
• Feedback Loop: Results flow back to the orchestrator for verification

Agent Communication Protocol (ACP)

Lightweight, REST-based messaging for interacting with legacy systems:

• Simplicity: Best for rapid prototyping and simple HTTP triggers
• Integration: Bridges modern agent ecosystems with existing infrastructure

Interaction Standards

• JSON-RPC: The foundation of MCP messaging. All tool calls and responses use this format.
• SSE (Server-Sent Events): For real-time updates and streaming results from remote tools.
• Stdio: The primary channel for local tool integration. Never mix logging with protocol messages on stdout.

Metadata Tagging

Every agent interaction should include metadata for traceability and quality assessment:

• agent_version: The semantic version of the agent core
• confidence_score: The agent's own assessment of its plan quality
• rationale: A concise explanation of the chosen strategy
• task_id: Reference to the tracked task or ticket being addressed

Cognitive Architecture

The Five-Layer Reasoning Stack

The Extended General Intelligence (EGI) framework defines how an AI agent processes information and produces actions:

1. Perception: Ingesting raw input (text, code, traces, terminal output) 2. Semantic Understanding: Mapping inputs to the current project context and ubiquitous language 3. Collaborative Reasoning: Evaluating multiple hypotheses and simulating outcomes 4. Orchestration: Sequencing tool calls and sub-tasks into a coherent plan 5. Meta-Cognition: Self-reflection and error correction (the critic layer)

Planning Modes

Agents operate in one of three planning modes depending on the situation:

• Goal-Driven (Proactive): The agent defines a high-level objective and works backward to create steps. Best for feature implementation and architecture tasks.
• Event-Driven (Reactive): The agent responds to external triggers such as a failing test or a lint error. Best for debugging and CI pipeline issues.
• Hybrid: The agent maintains a proactive plan but can pivot instantly based on new evidence. This is the preferred mode for production work.

Verifiable Goals

Every task must have a Definition of Done (DoD). Never consider a task finished without a verification signal:

• Test suite passes
• Build completes successfully
• User provides explicit approval
• Linter reports zero violations

Multi-Agent Orchestration

Complex tasks are broken down into specialized roles:

• Architect: Designs the system structure and interfaces
• Engineer: Implements the logic and writes tests
• Security: Audits for vulnerabilities and compliance
• SRE: Ensures observability, performance, and deployment safety

Cognitive Load Management

Agents must actively manage their own context window to maintain quality:

• Pruning: Removing irrelevant history that no longer affects the current task
• Summarization: Condensing long logs into actionable facts (single-sentence failure descriptions)
• Archiving: Moving stable information to long-term memory so it can be retrieved later without occupying active context

Context Engineering

The Information Hierarchy

Not all information is equal. Prioritize context in this order:

1. Current Request: The user's immediate goal 2. Explicit Rules: Mandatory protocols (skill instructions, CLAUDE.md, project rules) 3. Active File Content: The code being modified 4. Immediate Dependencies: Interfaces and types used by the active file 5. Historical Context: Relevant past commits or similar patterns

Token Optimization Techniques

• Symbol Search: Use grep or rg to find definitions rather than reading entire folders
• Partial Reads: Use offset and limit parameters when reading large files
• Semantic Summarization: Condense long error logs into a single sentence describing the failure mode and root cause

Noise Reduction

• Ignore List: Strictly exclude node_modules, .next, dist, and binary artifacts from context
• Redaction: Remove repetitive boilerplate or large data arrays that do not affect logic
• Deduplication: Do not include the same information from multiple sources

Few-Shot Anchoring

Providing canonical examples is significantly more effective than writing long lists of rules:

• Include one "Gold Standard" implementation for every new pattern
• Place the example close to where the agent will need it
• Use real code from the project rather than synthetic examples when possible

Structured Context Packing

Use tools like Repomix to bundle related files into a single, structured markdown artifact. This ensures the model understands file boundaries and hierarchical relationships between components.

Key practices:

• Bundle only the files relevant to the current task
• Include type definitions alongside implementation files
• Order files from most general (interfaces, types) to most specific (implementations, tests)

Memory Systems

Short-Term Memory (Context Window)

• Focus: Current session history and immediate task details
• Limit: Varies by model (200k to 2M tokens)
• Management: Handled by context engineering to keep relevant information prioritized

The context window is the most constrained resource. Every token spent on irrelevant history is a token unavailable for reasoning about the current task.

Mid-Term Memory (Working Context)

• Focus: Active project files, recently visited documentation, and in-flight feature specs
• Implementation: A persistent knowledge graph or vector index of the current repository

Working memory bridges the gap between immediate session context and long-term patterns. It stores facts about the current project that persist across sessions but are too volatile for permanent storage.

Long-Term Memory (Experience Repository)

• Focus: Historical patterns, past bugs, user preferences, and architectural lessons learned
• Mechanism:

1. Extraction: Summarizing key learnings after each completed task 2. Embedding: Storing in a vector database (Pinecone, Supabase Vector, or equivalent) 3. Retrieval: Automatic querying based on current task similarity

Long-term memory allows agents to avoid repeating mistakes and apply proven patterns from previous work.

The Memory Gate

Agents must not store sensitive data (keys, PII, credentials) in any memory tier.

• Run a secret scrub before persisting any memory vector
• Filter out environment variables, API tokens, and personal identifiable information
• Audit stored memories periodically for accidentally persisted secrets

Shared Memory (Team Knowledge)

Across a team, agents can share common project knowledge:

• Use project.json or memory.json in the project root to store collaborative facts
• Shared memory includes framework versions, architectural decisions, team conventions, and known issues
• Keep shared memory concise and actively pruned to prevent context pollution