info-tech-canon/infospace/patterns/AgenticDrivesFunctional.md

---
id: practice-pattern/agentic-drives-functional
title: AgenticDrivesFunctional
type: practice-pattern
scheme: practice-pattern/0.1
status: active
version: "0.1"
summary: Use agentic cross-repository work as a demand sensor, then turn repeated stable demands into direct functional interfaces.
aliases:
  - Agentic Demand-to-Interface Loop
  - Cross-Repo Demand Compiler
uses:
  - model/capability
  - model/governance
  - model/observability
  - model/task
related_patterns:
  - practice-pattern/interface-deprecation-strangler
known_uses:
  - repo-manager-scoped-identifier-registrar
owned_concepts:
  - AgenticDrivesFunctional
  - AgenticFallback
  - DemandSignature
  - FunctionalInterfaceCandidate
---

# AgenticDrivesFunctional

## Intent

Use agentic cross-repository communication to discover and refine missing
capabilities, but do not let recurring agent-to-agent work become a permanent
pseudo-interface. When a stable demand repeats, give its owner a direct API,
CLI, MCP, or equivalent functional surface so callers can obtain the result
without carrying a to-do across coding-agent sessions.

The recurring review question is:

> Can we provide the tasks we need do for others as interfaces they can use
> directly?

Here, *functional* means an interface that directly provides the required
service capability. It does not refer to the functional-programming paradigm.

## Context

Use this pattern where repositories have distinct ownership and their worker
agents can exchange suggestions, requirements, tasks, or workplans. A caller
sometimes needs a result owned by another repository and cannot obtain it from
an existing service API, CLI command, MCP tool, or other discoverable direct
surface.

The demand may initially be too novel or ambiguous to justify an interface.
The target repository's worker can interpret it when that repository next
handles open work. Over time, similar requests may reveal a stable service
capability that callers should no longer need an agent to relay.

## Problem

Cross-repository work records are exceptionally flexible: they preserve an
unresolved need until the right owner can interpret it. That flexibility has a
high marginal cost. Every relay adds queue time, context reconstruction, agent
turns, tokens, status checks, and opportunities to lose constraints. When a
third party must approve part of the work, the to-do and its approval state may
be carried through several sessions without producing the result.

Building an interface for every first request is not a solution. The first
request may be exceptional, its inputs and outputs may still be unclear, and a
premature contract creates maintenance and security obligations. The practice
must use agentic work to learn the right interface, then recognize when the
learning channel has become repetitive overhead.

## Forces

- Novel demands need interpretation, negotiation, and repository-owner
  judgment before their contract is known.
- Frequent demands need low latency and predictable cost.
- The target repository owns its capability, security policy, and compatibility
  obligations; a caller cannot define these unilaterally.
- Request text varies even when the desired outcome is semantically the same.
- An interface built from one anecdote can fossilize the wrong abstraction.
- A work-record queue tolerates exceptions well but scales poorly as a routine
  integration surface.
- APIs, CLIs, and MCP tools have development, documentation, versioning,
  observability, and support costs.
- Authorization, credential custody, destructive-action confirmation, and
  third-party approval remain necessary even when the surrounding work is
  automated.
- Approvals often outlive one agent session and therefore need durable,
  queryable state rather than conversational memory.
- The cheapest interface may expose only the stable preparation, validation,
  status, or evidence steps while retaining a governed human decision.

## Solution

Therefore, treat agentic cross-repository work as a metered fallback and demand
sensor, and compile repeated stable demand into a direct functional interface:

1. Search the owner's published API, CLI, MCP, capability, and reuse surfaces
   before creating cross-repository work.
2. If no adequate direct surface exists, route a typed record to the owning
   repository. Use a suggestion for an uncertain opportunity, a requirement
   for a needed outcome or constraint, and a task or workplan only after the
   owner accepts implementation work.
3. Preserve the request's provenance, desired outcome, inputs, constraints,
   urgency, and approval or authority boundary. Do not prescribe an
   implementation that belongs to the target owner.
4. Have the owner classify each inbound request by a semantic demand signature:
   desired capability, input shape, output or effect, authorization context,
   approval needs, and important quality constraints.
5. Review recurring demand signatures. Repetition triggers an interface review,
   not automatic implementation. Consider frequency, number of callers,
   stability, latency, token cost, failure rate, approval handoffs, and the cost
   of maintaining a contract.
6. Extract the stable functional core into the narrowest suitable direct
   surface. An API fits service-to-service calls, a CLI fits local or operator
   workflows, and MCP fits tool-mediated agent use. A combination may share one
   underlying capability contract.
7. Keep governed boundaries explicit. The interface may validate, plan,
   estimate, request approval, report approval state, execute an already
   authorized operation, and return evidence. It must not invent authority,
   expose credentials, or bypass a third party's approval.
8. Publish the interface with ownership, contract, examples, error semantics,
   authorization requirements, and discovery metadata. Migrate known callers
   and direct new callers to it.
9. Meter both direct use and continued agentic fallback. Retain the fallback for
   novel or exceptional cases, while phasing out the repetitive request shape
   when evidence shows the interface satisfies it.

The goal is not to eliminate agentic collaboration. It is to reserve that
expensive, general mechanism for ambiguity and change rather than routine
execution.

## Structure

```text
Caller repository
  -> discover direct surfaces
       -> adequate: call functional interface
       -> missing: route typed cross-repo demand
                      |
Target repository worker
  -> interpret and deliver the exceptional request
  -> record semantic demand signature + cost + approval boundary
                      |
Demand review
  -> novel/unstable: retain agentic fallback
  -> repeated/stable: define functional interface candidate
                      |
Owned API / CLI / MCP capability
  -> direct result, durable approval state, and evidence
  -> meter use and remaining fallback
```

The caller owns a clear statement of need. The target repository owns the
capability and interface. The approving party retains approval authority. The
demand review connects observations to an interface decision.

## Dynamics

### 1. Discover before routing

The caller first looks for a supported direct surface. This makes published
interfaces the normal path and prevents stale agent habits from generating
unnecessary tasks.

### 2. Route and learn

When the surface is absent, the caller sends the smallest typed demand record
that preserves the need. The target worker resolves or refines it during its
normal intake cycle and records the semantic demand signature. The work record
is both coordination and evidence of an interface gap.

### 3. Detect recurrence

At an owner-defined cadence, the target reviews semantically equivalent
requests rather than matching titles literally. Recurrence across time or
callers, repeated approval relays, high latency, or disproportionate token cost
can justify an interface candidate. Each repository declares thresholds suited
to its traffic; no universal occurrence count is implied.

### 4. Extract the stable core

The owner separates routine mechanics from judgment. Stable validation,
planning, execution, status, and evidence become callable operations. Novel
policy choices and exceptional negotiation remain agentic. Where third-party
approval is unavoidable, the interface makes the approval request and state
durable but leaves the decision with the authorized party.

### 5. Shift traffic and keep learning

Known callers adopt the new surface. Direct-use and fallback observations show
whether the abstraction is right. A fallback request with a new shape refines
the interface or remains an exception; repeated old-shape requests indicate a
discovery, usability, or coverage problem.

### 6. Strangle the repetitive relay

Once the direct interface is verified, use the evidence and staged guidance of
`InterfaceDeprecationStrangler` where appropriate to stop accepting the old
repetitive route as normal work. Keep an explicit path for genuinely novel
demands.

## Invariants

1. Callers try an adequate discoverable direct interface before routing work to
   another repository.
2. A cross-repository demand identifies the owning repository and preserves
   provenance, outcome, constraints, and authority boundaries.
3. Target owners classify recurrence by semantic outcome, not wording alone.
4. Repetition creates a review obligation, not an automatic obligation to
   publish an interface.
5. The target repository owns the extracted capability contract and its
   lifecycle.
6. The direct surface performs or returns the recurring function; merely
   automating creation of the same task is not functional extraction.
7. No task, API, CLI, or MCP call transfers authority that the caller does not
   possess.
8. Credentials and sensitive approval material remain in their governed
   custody boundary.
9. The interface exposes durable status and evidence when execution or approval
   is asynchronous.
10. Novel and exceptional requests retain a supported agentic path.
11. Interface and fallback observations are sufficient to decide whether to
    expand, correct, retain, or retire either path.

## Evidence

The practice should produce privacy-bounded evidence for:

- the direct surfaces checked before routing;
- typed inbound records and their owning repository;
- semantic demand signatures, occurrences, distinct callers, and time span;
- queue-to-result latency, agent turns or estimated token cost, retries, and
  failure outcomes;
- approval handoffs and time spent awaiting authorized decisions;
- the interface-candidate decision and locally chosen threshold or rationale;
- the stable input, output, effect, error, authorization, and evidence contract;
- adoption by known callers and direct-interface usage;
- continued fallback, classified as coverage gap, discoverability problem,
  exceptional demand, or caller migration debt; and
- the decision to expand, hold, redesign, or phase out a repetitive path.

Evidence should support an economic and operational judgment. Token count alone
does not prove an interface is worthwhile, and request frequency alone does not
prove the requested operation is safe to automate.

## Consequences

Repeated cross-repository work becomes faster, cheaper, more predictable, and
less dependent on coding-agent continuity. Repository owners learn interface
requirements from observed demand rather than speculation. Approval waiting
can become durable and queryable, reducing repeated explanation without
weakening the approver's control.

The cost is demand classification, metering, interface design, documentation,
compatibility management, and ongoing ownership. Some requests will remain too
rare or judgment-heavy to extract. Running both paths during adoption adds
temporary complexity, and a poorly chosen interface can encode accidental
workflow details as a long-lived contract.

## Failure Modes

- **TaskQueueAsAPI:** routine callers permanently create work records instead
  of receiving the function they need.
- **TaskCreationFacade:** a new API only creates the same downstream task and is
  presented as functional extraction.
- **OneRequestPlatform:** an interface is built after one exceptional demand
  without evidence of stability or recurrence.
- **LiteralDuplicateCounting:** differently worded instances of the same demand
  are missed, or similar words with different authority are conflated.
- **OwnerBypass:** callers dictate or implement another repository's contract
  without its owner accepting lifecycle responsibility.
- **ApprovalLaundering:** automation treats a routed task or prior conversation
  as authorization for a protected operation.
- **CredentialRelay:** secrets are copied through work records because the
  interface boundary was designed around convenience rather than custody.
- **GodInterface:** unrelated recurring requests are combined into an overly
  broad surface instead of bounded capabilities.
- **InvisibleInterface:** the owner builds a surface but does not publish it, so
  agents continue routing tasks.
- **NoEscapeHatch:** the direct interface replaces the only path for novel or
  exceptional cases.
- **UnmeteredMigration:** tasks are closed without evidence that callers use the
  replacement or that the recurring demand is satisfied.

## When Not to Use

Do not extract a direct interface when demand is genuinely one-off, inputs and
outcomes are still unstable, the work is principally negotiation or creative
judgment, or safe execution cannot be bounded by a service contract. Also do
not delay an obvious, already-defined interface merely to accumulate task
counts; existing standards, controlled callers, and clear ownership may already
provide sufficient evidence.

For emergencies, security incidents, or irreversible operations, follow the
applicable response and approval policy first. The pattern may improve later
handling, but it does not justify waiting for demand analysis or bypassing a
required decision.

## Known Uses

### Repo Manager scoped identifier registrar

HelixForge repositories repeatedly needed State Hub work-record UUIDs assigned
and projected. Coding agents could route the need to the repository or session
holding registrar authority, but each relay consumed context and could stall on
the governed mutation boundary.

`repo-manager` extracted the stable operation into
`rmgr registrar-reconcile`. The command discovers missing workplan and task
identifiers, checks repository cleanliness and upstream synchronization,
verifies the authoritative State Hub, serializes registrar use, invokes the
existing registration adapter, verifies writeback, commits the bounded change,
and can push it. It does not expose registrar credentials or let an ordinary
agent impersonate the registrar. Explicit `--confirm-primary` preserves the
authority-sensitive choice of hub.

This is a concrete demand-to-interface transition: the caller now invokes the
owned CLI directly and receives structured evidence rather than carrying a UUID
assignment task across repository agents. `ITC-WP-0017` itself was registered
through this surface on 2026-08-22.

Implementation references:

- repository: `repo-manager`;
- command: `rmgr registrar-reconcile`;
- implementation: `src/repo_manager/commands/registrar_reconcile.py`; and
- contract: `docs/work-record-uuid-derivation_v1.md`.

### General HelixForge cross-repository routing

HelixForge agents route suggestions, requirements, tasks, and workplans to
repository owners when no direct surface exists. This is observed use of the
demand-sensing fallback, not evidence that every routed demand deserves an
interface. Owners can use the resulting records to identify the next stable
capability worth extracting.

## Related Patterns

`InterfaceDeprecationStrangler`
(`practice-pattern/interface-deprecation-strangler`) complements this pattern
after extraction. `AgenticDrivesFunctional` discovers and establishes the
successor interface from repeated demand; `InterfaceDeprecationStrangler`
guides callers, meters remaining use, and gates retirement of the repetitive
legacy path on evidence.

## Adoption Checklist

- [ ] Publish and make existing API, CLI, MCP, and reuse surfaces discoverable.
- [ ] Define the typed cross-repository fallback and its ownership rules.
- [ ] Capture outcome, constraints, provenance, and approval boundaries.
- [ ] Classify inbound work by semantic demand signature.
- [ ] Choose a review cadence and locally meaningful candidate criteria.
- [ ] Compare relay latency and cost with interface lifecycle cost.
- [ ] Separate stable mechanics from judgment and protected decisions.
- [ ] Give asynchronous approvals durable status without moving authority.
- [ ] Publish the narrowest suitable functional surface and examples.
- [ ] Migrate known callers and meter direct use plus continued fallback.
- [ ] Preserve an explicit route for novel and exceptional demands.
- [ ] Record the evidence and decision for expansion, redesign, or retirement.

## Evolution

Version 0.1 names the feedback loop and records Repo Manager's scoped registrar
as its first complete known use. Further uses should test whether demand
signatures need a shared machine-readable form and whether repos benefit from a
common review report for interface-candidate economics.