agent-builder-codex

name: agent-builder-codex description: Designs, evaluates, and improves agentic harnesses for developer tools, assistants, workflow runtimes, copilots, and AI-powered products — including agents built on local and open-source models. Applies when work involves defining or reviewing tool-use architecture, permissions, workflow state, durability, context and memory systems, evaluation strategy, observability, user experience, framework selection, or phased implementation plans for an agentic system. tags: [agentic-harness, agents, architecture, evaluation, memory, observability, frameworks, multi-agent, local-models, open-source] category: developer-tools difficulty: advanced metadata: priority: 6 pathPatterns: - '/harness' - '/agent-runtime' - '/agent_runtime' - '/orchestrat' - '/workflow' - '/tool-registry' - '/tool_registry' - '/permission' - '/approval' - '/state-machine' - '/state_machine' - '/session' - '/memory' - '/eval' - '/retry' - '/ollama' - '/llama-cpp' - '/vllm' importPatterns: - '@modelcontextprotocol/' - 'langgraph' - '@langchain/' - 'langchain' - '@vercel/workflow' - 'langchain_ollama' - 'langchain-ollama' - 'deepagents' - 'ollama' - 'llama-cpp-python' - 'vllm' - 'outlines' - 'instructor' - 'pydantic_ai' - 'pydantic-ai' - 'smolagents' - 'dspy' - 'crewai' - 'autogen' - 'claude_agent_sdk' - 'claude-agent-sdk' bashPatterns: - '\bnpm\s+(install|i|add)\s+[^\n](langgraph|langchain|@vercel/workflow|@modelcontextprotocol)\b' - '\bpnpm\s+(install|i|add)\s+[^\n](langgraph|langchain|@vercel/workflow|@modelcontextprotocol)\b' - '\bbun\s+(install|i|add)\s+[^\n](langgraph|langchain|@vercel/workflow|@modelcontextprotocol)\b' - '\byarn\s+add\s+[^\n](langgraph|langchain|@vercel/workflow|@modelcontextprotocol)\b' - '\b(pip|uv|uvx)\s+(install|add)\s+[^\n]*(langchain|langgraph|deepagents|ollama|llama-cpp-python|vllm|outlines|instructor|pydantic-ai|smolagents|dspy|crewai|autogen|claude-agent-sdk)\b' promptSignals: phrases: - "agentic harness" - "agent harness" - "ai harness" - "harness architecture" - "agent architecture" - "agent runtime" - "agent workflow runtime" - "tool-use architecture" - "tool use architecture" - "tool calling system" - "tool registry" - "capability registry" - "permission layer" - "approval gate" - "human-in-the-loop" - "workflow state" - "session persistence" - "durable agent" - "durable workflow" - "resume after crash" - "crash-safe agent" - "retry and idempotency" - "context assembly" - "memory system" - "evaluation harness" - "replay evals" - "agent observability" - "operator visibility" - "multi-agent architecture" - "single agent vs multi-agent" - "stop reasons" - "local model agent" - "open source agent" - "ollama agent" - "self-hosted agent" - "on-device agent" - "offline-first agent" - "local llm tool calling" - "framework selection" - "memory substrate" allOf: - [agent, harness] - [tool, registry] - [permission, approval] - [workflow, state] - [resume, retry] - [context, memory] - [evaluation, harness] - [multi-agent, architecture] - [durable, agent] - [operator, visibility] - [local, agent] - [open-source, model] - [ollama, agent] anyOf: - "agent orchestration" - "approval workflow" - "tool-calling runtime" - "tool calling runtime" - "state machine" - "retry policy" - "framework for agents" - "which framework" - "which memory store" noneOf: [] minScore: 6

Agent Builder — Codex Variant

Use this skill as a router for designing, building, and evaluating agentic harnesses.

Read only the files you need. Do not load the entire reference set unless the request genuinely spans multiple subsystems.

Default posture:

• Bias toward lean, solo-maintainable architecture.
• Start with a single-agent design unless clear constraints justify more.
• Require an evaluation plan even for greenfield builds.
• Prefer explicit system boundaries, permission policy, and workflow state over prompt cleverness.
• Translate ideas into implementation phases, success criteria, and failure tests.
• When justifying multi-agent, cite empirical cost: single agent ≈ 4× chat tokens, multi-agent ≈ 15× chat tokens, 70%+ of multi-agent failures are systemic. See references/catalog/01-architecture-taxonomy.md.

Step 1 — Classify The Request

Choose one mode before reading reference files.

design

User is creating a new harness, planning a major rebuild, or asking for architecture, MVP shape, or implementation sequencing.

Default reads: references/methodology/01-principles-and-solo-dev-defaults.md, references/methodology/02-harness-shapes-and-architecture.md, references/methodology/08-design-and-build-playbook.md, references/catalog/01-architecture-taxonomy.md, references/templates/design-deliverable.md. Add references/catalog/06-local-and-open-source-models.md when the target is a local or open-source model.

evaluation

User has a harness and wants gaps, risks, missing primitives, UX upgrades, or architectural cleanup.

Default reads: references/methodology/01-principles-and-solo-dev-defaults.md, references/methodology/09-evaluation-and-improvement-playbook.md, references/catalog/02-harness-components.md, references/templates/evaluation-deliverable.md.

design + evaluation

User wants a target architecture and a way to verify it, compare it with an existing system, or define acceptance criteria before building.

Default reads: union of the two above.

catalog-lookup

User is asking a factual question about what exists — "which framework", "how does Anthropic's orchestrator work", "what memory substrate", "what's the best local model tool-calling stack". Route straight to the catalog. Do not dump methodology files.

Step 2 — Classify The Product Shape

If the target runs on a local/open-source model, also read references/catalog/06-local-and-open-source-models.md.

Step 3 — Read The Smallest Useful Reference Set

Methodology

• references/methodology/01-principles-and-solo-dev-defaults.md — default posture
• references/methodology/02-harness-shapes-and-architecture.md — shape, boundaries, lifecycle
• references/methodology/03-tools-execution-and-permissions.md — tool registries, approvals, trust tiers
• references/methodology/04-state-sessions-and-durability.md — resumability, retries, idempotency
• references/methodology/05-context-memory-and-evaluation.md — context, retrieval, provenance, evals
• references/methodology/06-agents-and-extensibility.md — multi-agent, plugins, hooks, skills
• references/methodology/07-ux-observability-and-operations.md — streaming UX, logs, budgets
• references/methodology/08-design-and-build-playbook.md — build-ready plan
• references/methodology/09-evaluation-and-improvement-playbook.md — findings, upgrade path
• references/methodology/10-example-requests-and-output-patterns.md — prompt/output examples
• references/methodology/11-codex-translation-notes.md — cross-client portability

Catalog

• references/catalog/01-architecture-taxonomy.md — Type I–V, stats, debates
• references/catalog/02-harness-components.md — six-component harness view
• references/catalog/03-frameworks.md — LangGraph / CrewAI / Pydantic AI / smolagents / DSPy / AutoGen / Bedrock
• references/catalog/04-memory-substrates.md — filesystem / vector / in-context, COALA, Voyager
• references/catalog/05-lab-patterns.md — Anthropic, OpenAI, Perplexity, Manus, Google, Devin, Cursor
• references/catalog/06-local-and-open-source-models.md — Ollama / llama.cpp / vLLM, Llama / Qwen / DeepSeek / Mistral, tool-call tiers, framework fit

Templates

• references/templates/design-deliverable.md
• references/templates/evaluation-deliverable.md

Do not rely on reference-to-reference chains. This file is the index.

Operating Rules

• Convert vague ambitions into concrete harness primitives.
• Push back on unnecessary complexity.
• Treat workflow state, permissions, context assembly, and evaluation as first-class architecture, not cleanup tasks.
• Separate universal harness primitives from product-specific manifestation.
• For evaluation requests, present findings first and improvement sequence second.
• For design requests, include how the design will be tested before calling it done.
• When recommending a framework, memory substrate, or multi-agent pattern, cite the catalog file you pulled it from.

Output Contract

For design

• recommended harness shape
• core primitives and subsystem boundaries
• MVP boundary
• phased implementation plan
• verification and acceptance criteria

For evaluation

• findings ordered by severity or leverage
• missing or weak primitives
• user experience and operational gaps
• prioritized upgrade path
• tests or checks that confirm the fixes

For design + evaluation

• target architecture
• comparison against current or likely failure modes
• implementation phases
• acceptance criteria
• evaluation plan covering regressions, safety, and UX

For catalog-lookup

• direct answer
• trade-offs relative to alternatives
• source citation

Final Check Before Responding

• Did you keep the design lean enough for a solo developer unless the request clearly demanded more?
• Did you avoid recommending multi-agent coordination by default?
• Did you include evaluation, not just construction?
• Did you give the user an operational path forward instead of abstract theory?
• If you recommended a framework, memory substrate, or multi-agent pattern, did you cite the catalog file?
• If the target is a local model, did you apply the stricter local-model posture from catalog/06?