## Terminology
This section defines the core nouns used in this specification. These terms are normative: other documents (PRD/PLAN/Wiki) should reuse them exactly to avoid ambiguity.
Quick mental model
Chat Mode decides _how a request enters the system_.
Executor is _what actually runs the turn_.
PAS is the _orchestration framework_ (not a selectable agent by itself).
Coding Agents are _executors_ that modify code (via adapters/transports).
Tool Calls are _structured function invocations_ inside messages.
Skills are _higher-level capabilities_ built from tools (and/or subflows).
Core entities
| Term | Definition | Examples | Notes |
| Model | The LLM weights/identity used to generate outputs. | gpt-5, claude-sonnet, qwen-coder | Models do not imply tools or orchestration. |
| Provider | The hosting/runtime that serves a model via an API. | OpenAI, Anthropic, local llama.cpp | Providers impose API shapes, limits, and tool-call constraints. |
| PAS (Orchestration Framework) | The hierarchical orchestration system coordinating role executors. | PAS runtime, role delegation, shared state rules | PAS is not an “agent tier” in the picker. |
| PAS Role Executor | A PAS role implementation that can run a turn and delegate work. | pas.architect, pas.director, pas.manager, pas.programmer | Roles are executors inside PAS. |
Execution dimensions (do not conflate)
| Term | Definition | Values / Examples | Notes |
| Chat Mode | Entry strategy: how a user request is routed into execution. | direct, auto, coding (or verdict_code) | This is a _routing/entry_ concept. |
| Executor | The runnable implementation that produces messages/actions for a turn. | none, pas.architect, coding_agent.aider, coding_agent.codex | This is the thing that runs. |
| Routing | The decision process selecting an executor. | Auto-router choosing direct vs pas. vs coding_agent. | Routing can vary per turn in auto. |
| Session | A continuity container for a multi-turn conversation. | session_id + history | Sessions exist even with zero tools (e.g., direct). |
Hard rule:
Chat Mode ≠ Executor.
PAS ≠ Executor. PAS contains executors (roles).
Coding agents, adapters, and transports
| Term | Definition | Examples | Notes |
| Coding Agent (Executor) | An executor focused on codebase changes (files/git/build). | Aider, Claude Code, SWE-Agent, Plandex, Codex CLI | These belong under coding_agent.. |
| Adapter | Verdict’s integration wrapper around an executor/tool. | AiderAdapter, CodexAdapter | Starts runs, passes context, parses results, normalizes outputs. |
| Transport | How the adapter communicates with the coding agent. | cli (spawn), rpc (daemon/session) | “Aider-RPC” is a transport mode, not a new agent. |
| Executor Capability Profile | What an executor is allowed to do. | read-only / patch-only / apply / commit | Used for policies per PAS role (e.g., Architect read-only). |
| Term | Definition | Examples | Notes |
| Tool | A single callable function exposed to an executor/LLM. | read_file, run_bash, git_diff, image_generate | Tools are invoked via tool calls inside messages. |
| Tool Call | A structured invocation request for a tool (name + args). | tool_calls: [{id, function:{name, arguments}}] | Tool calls are part of canonical message format. |
| Tool Result Message | The response message produced after executing a tool. | role="tool" + tool_call_id + content | Must link to the correct tool_call_id. |
| Skill | A higher-level capability composed of tools and/or subflows. | “Publish Project”, “Generate Images”, “Repo Refactor” | Skills may call many tools; treat as orchestration-level concepts. |
| Skill Invocation | Triggering a skill (macro) by name/contract. | invoke_skill("publish_project", ...) | Internally may create tool calls, sub-steps, or delegation. |
Data artifacts
| Term | Definition | Examples | Notes |
| Canonical Message Log | The single source of truth for a session: ordered messages[] in OpenAI-format. | [{role, content, tool_calls?}, {role:"tool", ...}, ...] | This is what enables resume/export/import. |
| Export | Serialized session package for portability. | {version, routing_mode, executor, messages[]} | Must be message-first (not tool-call-only). |
| Import | Ingesting an export into another surface (e.g., HMI). | create new HMI session + insert messages | Must mint a new session id; validate version/roles/size. |
Recommended naming conventions (implementation-facing)
Chat Mode identifiers: direct, auto, coding (or verdict_code)
Executor identifiers:
- PAS roles: pas.architect, pas.director, pas.manager, pas.programmer
- Coding agents: coding_agent.aider, coding_agent.claude_code, coding_agent.codex, etc.
Adapter identifiers (internal): adapter.aider, adapter.codex, etc.
Transport identifiers (internal): transport.cli, transport.rpc
Common anti-patterns (explicitly forbidden)
Treating PAS as a selectable executor (“PAS” is not an agent).
Calling “Direct” a “coding agent” (it is a Chat Mode; executor is effectively none).
Treating “Aider-RPC” as a separate agent (it is a transport for the Aider adapter).
Exporting “tool history” without messages[] (breaks Direct mode + loses context).
1) Vocabulary disambiguation table (the system needs these nouns)
| Element | Proposed term (use this) | What it is | Primary job | Has tools? | Stateful? | Examples |
| LLM weights | Model | The brain | Generate text/tool calls | N/A | N/A | gpt-5, sonnet, qwen-coder |
| Vendor endpoint | Provider | Where the model is hosted | Completion API + limits | N/A | N/A | OpenAI, Anthropic, local llama.cpp |
| How a chat enters system | Chat Mode | Entry strategy | Decide “who runs this” | Depends | Depends | Direct, Auto, Verdict-Code |
| The thing that runs a turn | Executor | A runnable agent implementation | Produce assistant message(s) | Maybe | Maybe | PAS role executor, Coding Agent executor |
| PAS role | PAS Role Executor | Orchestration role | Plan/delegate/verify | Maybe | Usually stateless | Architect/Director/Manager/Programmer |
| External coding tool | Coding Agent | A code-changing executor | Edits repo / runs tools | Yes (via adapter) | Often stateful-ish | Aider, Claude Code, SWE-Agent |
| How we talk to a coding agent | Adapter | Integration wrapper | Start/run/stream/parse | N/A | N/A | AiderAdapter, ClaudeCodeAdapter |
| How adapter connects | Transport | Comm method | CLI vs RPC | N/A | N/A | CLI (spawn), RPC (daemon/session) |
| Tool calling | Tool Call | Structured function invocation | Run a tool | Yes | No | run_bash, read_file, git_diff |
| Skill calling | Skill Invocation | “Macro tool” / capability pack | Higher-level routine | Yes (composed) | Maybe | “Publish project”, “Generate images” |
| Tool catalog | Tool Registry | Available functions | Schema + permissions | N/A | N/A | investigation/execution/git tools |
| Session continuity | Session Message Log | Canonical history | Resume + export/import | N/A | Yes | OpenAI-format messages[] |
Key rule: the UI picker should never mix
Chat Modes and
Executors without labeling them, because they’re different dimensions.
2) Your current picker list mapped into the taxonomy
Below, I’m treating your list as “Executor Picker Entries”, but I’m explicitly labeling what each really is:
| UI Item | Proposed category | What it actually is | Tools available | Where it runs | Typical use |
| ⚡ Direct | Chat Mode | Raw LLM turn handler (no orchestration) | None | Gateway → Provider | Fast Q&A, brainstorming |
| 🔄 Auto | Chat Mode | Router that selects an executor per turn | Depends on chosen executor | Gateway | “Do what’s best” routing |
| 🤖 Verdict-Code | Executor (Coding Agent) | Native Verdict coding executor | Yes | Local / Verdict runtime | Default coding path |
| 📬 Claude-Code | Executor (Coding Agent) | External coding executor via VCCA | Yes | External CLI/service | Anthropic workflow |
| 💼 Aider | Executor (Coding Agent) | External diff-first executor | Yes | Local CLI | Patch/diff-first edits |
| 🤖 SWE-Agent | Executor (Coding Agent) | Autonomous SWE-bench style executor | Yes (often via Docker) | Local + Docker | Long autonomous fix loops |
| ✍️ Mini-SWE | Executor (Coding Agent) | Lightweight bash-style executor | Yes | Local | Simple bash + edits |
| 📋 Plandex | Executor (Coding Agent) | Plan-first multi-file executor | Yes | Local | Plan→apply workflows |
| 🛠️ GPT-Engineer | Executor (Coding Agent) | CLI project generator | Yes | Local | New project scaffolds |
| 🅲 OpenAI Codex | Executor (Coding Agent) | Official coding CLI executor | Yes | Local + OpenAI | Codex-driven edits |
| 🔮 Open Interpreter | Executor (Tool Runner) | NL-to-execution shell loop | Yes | Local | “Run stuff” interactively |
Naming fix: keep the UI header as
Chat Mode (Direct/Auto/“Coding”) and then
Coding Agent (Verdict-Code, Aider, Claude-Code, …). Right now they’re in one bucket, which is the source of confusion.
3) Is “Aider-RPC” another coding agent?
No. “Aider-RPC” is not a new agent. It’s a transport/back-end mode for the Aider adapter.
Think of it like this:
Aider (Executor) = “the thing that decides edits and produces diffs”
AiderAdapter (Adapter) = “Verdict’s wrapper around Aider”
CLI mode (Transport) = spawn aider … each run, parse stdout
RPC mode (Transport) = keep an aider daemon/session alive, send requests, get structured responses
Utility-wise, RPC buys you:
faster repeated turns (no process cold start)
persistent in-agent context (if aider maintains it)
cleaner streaming + structured outputs (if RPC supports it)
RPC costs you:
process lifecycle management (crashes, orphan sessions)
concurrency and locking (two calls to same session)
version skew / protocol drift
harder debugging than “run the CLI and read stdout”
That’s why I keep saying “defer Aider-RPC”: it’s not required to achieve multi-turn (multi-turn is message-log persistence). RPC is an optimization / ergonomics layer for _one_ coding agent.
4) “Attach a coding agent to any PAS agent” — yes, with one clean interface
Conceptually, PAS roles shouldn’t “be” the coding agent. They should delegate code execution through a single abstraction:
CodeExecutor (interface)
configured by coding_agent_id
can be called by _any_ PAS role if allowed
ASCII: the correct mental model
(Chat Mode) User ──► Gateway ───────────────► Router (direct | auto | coding) │ ├─ direct: Provider(model) ──► assistant msg │ └─ executor: (PAS role OR Coding Agent) │ ├─ PAS Role Executor (Architect/Dir/Mgr/Prog) │ │ │ ├─ thinks / plans / delegates │ │ │ └─ may call CodeExecutor.run(...) <─── attach point │ └─ Coding Agent Executor (Aider / Codex / ...) │ ├─ uses tools (edit files, bash, git, etc.) └─ returns patches/results All turns append to: Session Message Log (messages[])
So yes: any PAS role can call a coding agent, but you probably want a safe default policy for sanity.
5) Second table: how I’d organize PAS↔CodingAgent attachments
Here’s a clean “capability matrix” (recommended defaults + optional power-user overrides):
| PAS Role Executor | Primary job | Default coding-agent attachment | Why | Optional override? |
| Architect | requirements + top-level plan | None | keep Architect pure; prevents “random edits” | Allow “read-only analysis” via coding agent |
| Director | decomposition + strategy | Optional (read-only / diff review) | can request diffs but shouldn’t apply | Allow “request patch but don’t apply” |
| Manager | task planning + verification | Yes | good place to run patch generation iteratively | Full apply allowed under policy |
| Programmer | execution + diffs + commits | Yes (default) | the “doer” | Full apply/commit allowed |
Policy knob: “Which roles may call CodeExecutor, and with what permissions (read-only / patch-only / apply / commit)?”
This keeps your “attach anywhere” capability without turning the system into chaos.
Practical renaming recommendation (so the whole project stops drifting)
If you adopt just these three labels consistently, 80% of ambiguity disappears:
Chat Mode: direct | auto | coding
Executor: pas. | coding_agent.
Adapter + Transport (internal only): aider + (cli|rpc) etc.
Then “PAS” stays what it really is: the orchestration framework, not “an agent in the picker.”
