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

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

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.