Core primitives

You can implement this in any framework, but you need consistent primitives:

• Session: one conversation thread over time.
• Artifact: session-persistent outputs (plans, decisions, logs, structured data).
• Agent: objective + correctness definition + procedure + capabilities it can use.
• Subagent: delegated agent run with tight I/O and isolation.
• Skill: on-demand knowledge module; may reveal additional capabilities when loaded.
• Tool: privileged action interface (I/O, code exec, network calls).
• API Endpoint: a stable programmatic operation exposed by a service.
• Capability: anything usable (skill, tool, subagent, endpoint set).
• Visibility: what’s currently known/usable by the agent (must be scoped + dynamic).

Let me ground this in the example from the specification, because abstract principles stick when you can see them in action.

Scenario: Planning a Dinner for Eight

You invoke the agent: “Plan a dinner party for 8 people.”

Flow A: Always-Needed Work

The agent begins with its base context. It sees:

• Its objective: create a viable dinner plan
• Its correctness definition: must satisfy budget, timing, and guest preferences
• Always-needed capabilities: basic planning workflow, artifact generation

It doesn’t see anything about allergies, wine pairings, or outdoor contingencies. Those capabilities literally do not exist in its visible universe.

The agent asks for your budget, preferred cuisine, and date. It proposes a menu: grilled salmon, roasted vegetables, chocolate tart. It generates a shopping list and prep schedule. Clean, focused, efficient.

Then you drop the critical detail: “One guest has a severe peanut allergy.”

Flow B: Optional Capability Discovery via Skill Load

Here’s where Progressive Discovery activates. The agent recognizes that “peanut allergy” triggers the dietary_restrictions skill. It loads this skill, and only now does the allergy-safe planning capability become visible.

The skill provides:

• Targeted knowledge: what questions to ask, how to interpret restrictions, what “safe enough” means
• Newly revealed capabilities:
  • Subagent allergy_menu_planner
    • Endpoint ingredient_checker

The agent’s visible universe expands just enough to handle this specific constraint. It doesn’t suddenly see every dietary restriction subagent in the system, just the ones relevant to allergies. It doesn’t see the wine pairing tool. It doesn’t see the outdoor contingency planner.

The agent invokes allergy_menu_planner, which uses the ingredient_checker endpoint to validate the menu (this endpoint would only be revealed to the subagent). It returns a revised plan: safe substitutions, risk notes, updated shopping list. The task completes without the agent ever having to consider irrelevant capabilities.

Going back to our dinner plan example:

Flow C: Preconditions Failure

Now imagine you say: “Plan a dinner party” but refuse to specify a budget. The agent attempts to use the menu_proposal capability, but the policy layer checks for the budget artifact. It’s missing. The system blocks execution and returns:

Missing: budget parameter
Action: Please provide a maximum per-person budget (e.g., "under $30 per person")

Short, actionable, and doesn’t leak implementation details. The agent doesn’t start hallucinating a budget. It doesn’t expose internal artifact plumbing. It just tells you what’s missing and how to fix it.

Rule 1: Explicit Classification

Every capability must be documented as either always-needed or optional. This isn’t just for the system; it’s for the humans designing the system. If you can’t justify why something is always-needed, it’s optional.

Rule 2: Skill Load Reveals Capabilities

When a skill loads, it can reveal:

• Subagents
• Endpoints
• Additional skills (skills can be nested)
• Tools

The key: these must be invisible before load. Not disabled, not commented out, invisible.

Rule 3: No Mirror Skills

This is a common anti-pattern: creating a skill that exists solely to point to an always needed capability. If your “requirements” subagent is always needed, don’t create a “requirements_skill” that just reveals it. That’s ceremony that adds no value. Skills justify their existence by either providing deep knowledge and (optionally) revealing optional capabilities.

Rule 4: Reuse Without Global Visibility

A subagent can be invoked from multiple places, but that doesn’t mean it should be visible everywhere. Same with other resources. The ingredient_checker endpoint might be used by both the dinner planner and the meal prep planner, but each parent agent only sees it when the appropriate skill loads. Reuse doesn’t require global exposure.

Rule 5: Prerequisites are Enforced Deterministically

A policy layer blocks capability use when prerequisites aren’t satisfied and returns a short, actionable error:

• what’s missing,
• what to do next,
• without leaking internals.

Rule 6: Artifact Exposure Is Minimized

Just because an artifact exists doesn’t mean the agent should see it. Internal reasoning artifacts should stay internal. Only return what the caller actually needs, a summary, a result, a pointer. Exposing all raw artifact content is a failure of interface design.

Progressive-Discovery Agent System

Purpose

An agentic system where each agent is given only the minimum necessary information and interfaces required to meet its objective’s correctness criteria.

Key idea: progressive discovery.

• Some knowledge and capabilities are always needed and should be available from the start.
• Other knowledge and capabilities are optional and should remain invisible until they become relevant, at which point they are revealed by loading a skill.

This document defines the primitives, rules, and usage flow for such a system without assuming any particular implementation or framework.

Goals and correctness criteria

Goal 1: Minimum necessary exposure per agent

Meaning: For an agent’s objective, expose only what is strictly required to satisfy its correctness definition. Do not expose unrelated knowledge, capabilities, or interfaces.

Correctness criteria:

• If a capability is not needed for an agent’s objective, it must not be visible to that agent (not even name/summary).
• If a subagent is not needed, it must not be visible to that agent (not even name/summary).
• If an optional capability is not currently relevant, its details must not be loaded into the agent context.

Goal 2: True progressive discovery (dynamic visibility)

Meaning: Optional capabilities are revealed only when a relevant skill is loaded. Before that moment, the agent should not be able to see or use them.

Correctness criteria:

• Loading a skill can change what the agent can see/use (visibility is dynamic).
• Before the skill is loaded, the newly revealed items must be fully invisible.
• The system must support this dynamic visibility change without requiring the agent to carry long lists “just in case”.

Goal 3: Composability without forcing a single usage mode

Meaning: Any agent may be used as a standalone entry point, as a delegated subagent, or both, depending on what the system designer chooses.

Correctness criteria:

• It is possible (not mandatory) for an agent to run standalone.
• It is possible (not mandatory) for the same agent to be invoked as a subagent.
• Agent behavior does not rely on who called it unless explicitly part of the contract.

Goal 4: Programmatic prerequisites and sequencing

Meaning: Prerequisites (e.g., required artifacts, confirmations, configuration) must be enforced by deterministic checks, not by the model “remembering rules”.

Correctness criteria:

• The system blocks invoking a capability when prerequisites are not satisfied.
• The failure response is short and actionable:
  • what is missing,
  • what to do next,
  • without exposing internal implementation details.

Goal 5: Session-scoped artifacts with zero cross-session interference

Meaning: Artifacts produced in one conversation must not affect any other conversation, and must remain available when revisiting the same conversation.

Correctness criteria:

• Each session’s artifacts are isolated from other sessions in a way that prevents conflicts and leakage.
• Revisiting the same session retains access to its artifacts.

(Implementation is intentionally unspecified: isolation may be achieved by directory namespacing, storage keys, separate databases, etc.)

Goal 6: Programmable task-specific functionality (endpoints + code execution)

Meaning: For task-specific “business logic” (agent-specific operations), prefer:

• a small set of stable endpoints (API surface), and
• the ability for an agent to write/run code that calls those endpoints as needed.

This enables flexible control flow and avoids encoding task logic into many tiny actions.

Correctness criteria:

• The system defines a stable endpoint surface for the task domain.
• Agents can run code that calls endpoints to accomplish complex tasks.
• Endpoint documentation is revealed only when relevant (typically via skill load).

Primitives (definitions)

Session

A session is a single conversation instance (a single run/thread over time). It contains:

• user interaction history,
• agent/subagent interactions,
• artifacts produced during that session.

Artifact

An artifact is a persistent output generated during a session. Examples:

• requirement summaries, decisions, plans, reports,
• structured data, documents, logs.

Artifacts must be isolated by session (Goal 5).

Agent

An agent is a unit of work defined by:

• an objective,
• a correctness definition (what “done and correct” means),
• a procedure/rubric (how it works),
• the capabilities it can use.

Subagent

A subagent is an agent invoked by another agent. A subagent run must be contextually isolated enough that:

• deep internal reasoning does not bloat the parent,
• only the necessary outputs are returned to the parent.

Whether subagents can invoke other subagents is implementation-dependent.

Skill

A skill is an on-demand knowledge module. It can contain:

• targeted knowledge (definitions, heuristics, checklists, rules), and optionally
• declarations that reveal additional capabilities (subagents, endpoints, tools, additional skills) when the skill is loaded.

Skills are the primary mechanism for progressive discovery.

Tool

A tool is an action interface for interacting with the environment. Typical examples:

• reading/writing files (artifact I/O),
• running code (script execution),
• calling network services.

Tools should be treated as a privileged surface and kept minimal.

Endpoint (API)

An endpoint is a stable programmatic operation exposed by a service (local or remote). Endpoints are the preferred interface for task-specific logic because agents can write code to compose them.

Capability

A capability is anything the agent can choose to use, such as:

• a skill (load knowledge),
• a subagent (delegate a job),
• a tool (perform an action),
• a set of endpoints (domain operations).

Visibility

Visibility is the set of capabilities an agent is currently aware of and allowed to use. Visibility must be:

• scoped (Goal 1),
• dynamically changeable when a skill is loaded (Goal 2).

System rules (how the system must behave)

Rule 1: Always-needed vs optional capabilities

For each capability, explicitly classify it as either:

• Always-needed

  • The agent must have it available from the start (base specification/prompt).
  • Rationale: hiding it behind a skill does not reduce exposure if it is always used.

• Optional

  • The agent must not see it by default.
  • It becomes visible only when a relevant skill is loaded.
  • Rationale: prevents exposing “rare branches” to the agent’s base context.

This decision is part of system design and must be documented per capability.

Rule 2: Skill load can reveal capabilities

When an optional capability becomes relevant, the agent loads a skill. Loading a skill may reveal:

• one or more subagents,
• endpoint documentation and base URLs,
• additional tools (if the platform supports it safely),
• additional skills.

Key requirement: these revealed items must be invisible before the skill load.

Rule 3: No “mirror skills” for always-needed capabilities

Do not create a skill whose only purpose is to point to an always-needed capability. Example of what to avoid:

• a “requirements skill” that only points to the requirements subagent that the parent always uses anyway.

A skill is justified when it provides targeted knowledge or reveals optional capabilities that should not be in the base context.

Rule 4: Reusable subagents are allowed and expected

The system must support reuse: a subagent can be invoked from multiple places when needed.

Constraints:

• reuse must not force global visibility,
• only the agents that legitimately need the reusable subagent can see it,
• other agents must remain unaware of it.

(How this is enforced is implementation-dependent; the requirement is that visibility remains scoped.)

Rule 5: Preconditions are enforced by a deterministic policy layer

The system must include a policy component that can:

• evaluate prerequisites before a capability is used,
• deny execution if prerequisites are not satisfied,
• return a short, actionable message.

Prerequisites may include:

• required artifacts exist (or meet a minimum quality/format),
• user confirmation is present,
• environment/configuration is ready.

Rule 6: Artifact exposure is minimized

Artifacts can exist at many internal levels. Only expose artifact information to an agent if it is required for that agent’s objective.

Practical guidance:

• Prefer returning a structured summary or final result rather than internal artifact plumbing.
• Expose raw artifact content or identifiers only when the caller truly needs them.

Standard usage flow (order of operations)

Flow A: Always-needed work

1. Agent begins with its base context:
   • objective,
   • correctness definition,
   • procedure,
   • always-needed capabilities.
2. Agent proceeds using only the always-needed capabilities.

Flow B: Optional capability discovery via skill

1. Agent detects that an optional capability might be relevant.
2. Agent loads the relevant skill.
3. Skill provides:
   • targeted knowledge, and/or
   • newly revealed capabilities (subagents, endpoints, etc.).
4. The system updates visibility: the newly revealed items become available.
5. Agent uses the newly revealed capability.
6. Agent returns the necessary result to its caller/user.

Flow C: Preconditions failure

1. Agent attempts to use a capability.
2. Policy layer checks prerequisites.
3. If prerequisites are missing:
   • execution is blocked,
   • system returns a short “what’s missing / what to do next” message.

Example: Planning a dinner party with optional “allergy-safe menu” capability

Objective

Create a dinner party plan that satisfies:

• budget and timing constraints,
• guest preferences,
• required logistics (shopping list, cooking schedule),
• and any confirmed dietary restrictions.

Always-needed capabilities (visible from start)

• A “basic planning” procedure:
  • gather date/time, guest count, budget, and constraints,
  • propose a menu,
  • produce a shopping list and prep schedule.
• A way to produce artifacts (e.g., “plan summary”, “shopping list”).

These are always needed for any dinner party plan, so they must be in the base context.

Optional capability: “allergy-safe menu planning”

This capability is only needed if allergies or strict dietary requirements are present (e.g., peanut allergy, celiac, vegan).

Progressive discovery requirement:

• Before allergies are mentioned/confirmed, the agent must not see:
  • allergy-safe subagents,
  • allergy endpoint documentation,
  • specialized checklists.

Skill: dietary_restrictions

When loaded, it reveals:

• targeted knowledge:
  • what questions to ask to confirm restrictions,
  • how to interpret common restrictions safely,
  • what “safe enough” means (correctness definition for this branch).
• newly visible capabilities:
  • Subagent allergy_menu_planner:
    • generates allergy-safe menu alternatives,
    • outputs substitutions and risk notes.
  • Endpoint docs ingredient_checker:
    • takes ingredients and returns risk flags (e.g., “contains peanuts”),
    • intended to be called from code for a candidate menu.

Example flow

1. User: “Plan a dinner party for 8 people.”
2. Agent uses always-needed planning capabilities: proposes menu + schedule.
3. User: “One guest has a severe peanut allergy.”
4. Agent loads skill dietary_restrictions.
5. Visibility updates: allergy_menu_planner and ingredient_checker become visible.
6. Agent invokes allergy_menu_planner and/or runs code that calls ingredient_checker for the proposed menu.
7. Agent returns a revised plan:
   • safe menu,
   • substitutions,
   • explicit risk notes,
   • updated shopping list.

This example demonstrates:

• optional complexity stays hidden until relevant,
• a skill can contain deep knowledge and reveal subagents/endpoints,
• the base agent remains lean until the optional branch is activated.

Acceptance checklist (implementation-independent)

1. Visibility

   • Optional capabilities are invisible before the relevant skill is loaded.
   • Always-needed capabilities are visible from the start.

2. Dynamic progressive discovery

   • Loading a skill changes what the agent can see/use.

3. Preconditions

   • Capability usage is blocked when prerequisites are missing.
   • Failure message is short, actionable, and does not leak internals.

4. Artifacts

   • No cross-session interference.
   • Revisiting a session retains artifacts.

5. Reuse

   • A reusable subagent can be invoked from multiple places without becoming visible everywhere.

Nice-to-have capabilities

This section describes additional capabilities that are not required for the core system, but materially improve reliability, cost, safety, and operability at scale.

1) Advanced observability

Basic logging of “what happened” is assumed. Beyond that, the system should support deep observability across agents, skills, tools, endpoints, and policy decisions.

Capabilities:

• Distributed traces with spans for:
  • skill loads,
  • capability visibility changes,
  • subagent invocations,
  • tool calls,
  • endpoint calls,
  • policy/prerequisite checks and denials,
  • artifact reads/writes.
• Consistent correlation identifiers:
  • session_id, run_id, agent_id, capability_id, artifact_id.
• Metrics (counters, histograms, gauges) for:
  • token usage by agent/skill/tool,
  • latency per phase and per capability,
  • success/failure rates by capability,
  • precondition failure rates,
  • “optional capability activated” frequency,
  • artifact size growth (proxy for context bloat risk),
  • endpoint call volume and error rate,
  • retries, fallbacks, and replay frequency.
• Result-quality metrics (system-specific), e.g.:
  • plan completeness checks,
  • number of unresolved questions,
  • acceptance criteria present/absent,
  • user edits after generation (proxy for correctness gaps).
• Redaction-aware logging:
  • structured logs with fields marked as sensitive,
  • safe-to-log summaries for model prompts and artifacts,
  • configurable PII/secret detection.

Correctness criteria:

• Every execution step is traceable end-to-end with a session/run correlation id.
• Observability data is sufficient to diagnose failures without reading full prompts.

2) Configurable retries and fallbacks

The system should handle transient failures and uncertain steps deterministically and safely.

Capabilities:

• Retries configurable per capability/tool/endpoint:
  • max attempts,
  • backoff policy (exponential, linear, jittered, windowed),
  • retryable error classes vs non-retryable,
  • timeouts and circuit breakers.
• Fallback strategies configurable per step, e.g.:
  • alternate model/provider,
  • alternate endpoint region,
  • reduced-scope execution (partial output),
  • “ask user” fallback when uncertainty is high,
  • cached results reuse when safe.
• Idempotency support:
  • idempotency keys for tool/endpoint calls,
  • safe re-run semantics for artifact generation steps.

Correctness criteria:

• Retries do not create duplicate side effects.
• Fallbacks are explicit, logged, and preserve invariants (no capability leakage, no cross-session artifact conflicts).

3) Rate limiting + queue-based batch processing

To reduce cost and avoid overload, the system should support controlled throughput, especially for batch workloads (e.g., processing many files, PRs, tickets, records).

Capabilities:

• Centralized rate limiting per:
  • endpoint,
  • tool type,
  • external integration,
  • model/provider,
  • account/tenant.
• Automatic queue management:
  • enqueue batch jobs,
  • concurrency controls,
  • per-job priorities,
  • dead-letter queues for repeated failures,
  • batch chunking (size/time-based).
• Cost-aware scheduling:
  • run during off-peak windows,
  • use cheaper models for low-risk steps,
  • defer expensive optional capabilities unless triggered.
• Progress reporting:
  • job status, percent complete, ETA,
  • per-item failure reporting and retry controls.

Correctness criteria:

• Batch execution respects rate limits without manual intervention.
• Failures are isolated to items; the batch does not become “all-or-nothing”.

4) External integrations with multi-account and multi-identity management

For systems that interact with third parties (GitHub, Jira, Slack, cloud providers), account handling becomes a major source of risk and complexity.

Capabilities:

• Identity profiles per integration:
  • personal account,
  • machine user,
  • read-only account,
  • break-glass/admin account.
• Per-capability identity selection:
  • e.g., “read code” uses read-only, “merge PR” uses machine user.
• Least-privilege policies and audit trails:
  • explicit permission mapping per endpoint/tool/integration action,
  • clear logs showing which identity performed which action.
• Secret storage and rotation support:
  • scoped tokens,
  • automatic rotation,
  • short-lived credentials where possible.
• Environment partitioning:
  • separate dev/staging/prod integration contexts,
  • per-session or per-project integration selection.

Correctness criteria:

• Actions are performed under the minimum required identity.
• All external side effects are attributable and auditable.

5) Partial executions, checkpoints, and replays

The system should support robust “resume and replay” semantics without redoing work or reintroducing side effects.

Capabilities:

• Step-level checkpoints:
  • store step outputs and relevant inputs,
  • store capability visibility state at the time of execution.
• Partial execution modes:
  • run only selected steps,
  • “dry run” mode with no external side effects,
  • “validate only” mode (checks artifacts/contracts without regeneration).
• Replays:
  • deterministic replay from a checkpoint,
  • replay with changed inputs (e.g., updated requirements),
  • replay with changed configuration (e.g., new model) while preserving artifacts.
• Provenance tracking:
  • which artifact came from which run, with which inputs and versions.
• Side-effect control:
  • ensure replays do not repeat non-idempotent actions unless explicitly approved.

Correctness criteria:

• Replays produce traceable outcomes and do not duplicate side effects.
• Users can resume from checkpoints without losing session isolation or visibility rules.

Additional nice-to-haves (recommended)

6) Formal capability contracts and schema validation

As systems grow, informal “expected input/output” is a common source of errors.

Capabilities:

• Structured schemas for:
  • agent inputs/outputs,
  • skill outputs (revealed capabilities),
  • artifacts,
  • endpoint request/response types.
• Runtime validation:
  • reject malformed inputs/outputs early,
  • strict vs permissive validation modes.
• Compatibility/versioning:
  • schema versions per capability,
  • migrations for artifacts between versions.

Why it helps: reduces silent failures, enables safer reuse and partial replays.

7) Safety controls and sandboxing for code execution

If agents can execute code, guardrails are essential.

Capabilities:

• Sandboxed execution environments:
  • filesystem and network restrictions,
  • resource limits (CPU/memory/time),
  • explicit allowlists for outbound destinations.
• Policy-driven “dangerous operation” approvals:
  • require explicit user confirmation for destructive actions.
• Secure-by-default defaults:
  • no ambient credentials,
  • scoped credentials injected only when needed.

Why it helps: reduces security risk without relying on prompt discipline.

8) Quality gates and automated review layers

To improve correctness, introduce automated checks that do not depend on the model’s self-assessment.

Capabilities:

• Automated validators:
  • required sections present,
  • contradictions detection,
  • missing acceptance criteria,
  • dependency graph completeness checks.
• Review subagents or deterministic checkers:
  • run “plan review” step that critiques outputs against the objective rubric.
• Confidence and uncertainty reporting:
  • explicitly track what is confirmed vs assumed,
  • enforce “no assumptions” rules programmatically where possible.

Why it helps: prevents superficially plausible but incorrect outputs.

9) Cost controls and budgeting

Especially important when optional capabilities can be expensive.

Capabilities:

• Per-session and per-project budgets:
  • token budgets,
  • time budgets,
  • endpoint call budgets.
• Adaptive execution:
  • downgrade models when risk is low,
  • stop early and ask user when budget is exceeded,
  • defer optional checks unless triggered.

Why it helps: keeps the system predictable and controllable in real usage.