Ashay Kubal, Product Leader, Enterprise AI & ML

AFIX — An Open Schema for Cross-Enterprise Agent Governance

Thu, 30 Apr 2026 19:36:35 GMT

From Profile to Interchange

In my first article in the AI governance series, I compared the AI governance evolution to the FIX moment. It ended ended with a specific proposal: build a Financial Services Profile for Google’s A2A protocol: domain-specific extensions declaring agent identity, compliance metadata, entitlement boundaries, and liability allocation. By my understanding at the time, the logic was clean. A2A provides agent-to-agent coordination. Financial services needs governance at the organizational boundary. Extend the protocol with a domain-specific profile, the way RIXML extended XML for research exchange. Ship it through FINOS.

Then I sat down to pen a concrete proposal to paper and the ensuing research made me realize that my original thought process was too narrow. Over the last four weeks of deep research that included reading hundreds of sources, five stress-tests, four steel-manned counterarguments that I built for myself, and a hostile reviewer pass designed to find what I’d missed, I came to a much different conclusion.

The first thing that broke the A2A extension thesis was where cross-enterprise agent interactions are actually happening in financial services. Not A2A. MCP.

Bloomberg launched AI Ready Data on MCP in early 2026: governance middleware wrapping every agent interaction with identity verification, access control, audit logging, rate limiting, and metering. All proprietary, all Bloomberg-native.¹
FactSet did the same with AI Data Mesh: MCP as a primary distribution channel with governance layered on top, no shared vocabulary with Bloomberg’s implementation.²
LSEG shipped Trusted AI Ready Content with equivalent governance controls, a third independent implementation of the same categories.³

Three data vendors with their own governance stacks. Identical categories (identity, access control, audit, metering) built independently, on the same protocol, with no reported interoperability between them. The parallel to pre-HL7v2 healthcare, where every hospital exchanged lab results through custom point-to-point interfaces, is precise.

Then the pattern accelerated:

Kong and Apigee shipped MCP-specific gateway infrastructure (identity enforcement, ACLs, audit logging, rate limiting) making governance middleware available as API gateway configuration rather than custom engineering.⁴
On April 14, 2026, while I was drafting this article, Cloudflare published a full reference architecture for enterprise MCP governance. Not a whitepaper but a full production system, internally validated across their product, sales, marketing, and finance teams before publication: Cloudflare Access as OAuth provider, MCP Server Portals aggregating upstream servers behind a single enforcement point, DLP (Data Loss Prevention) scanning via Gateway body inspection, shadow MCP detection monitoring corporate traffic for unauthorized agent protocol usage, and full audit logging with SIEM export via Logpush.⁵
Days later at Cloud Next, Google shipped Agent Gateway as part of Gemini Enterprise Agent Platform, the first gateway covering both A2A and MCP in a single enforcement surface, with Symantec DLP integration and Model Armor for prompt injection protection.⁶
Oracle published a runtime governance framework reframing the unit of control from the model response to the governed action trajectory: four-layer control model, structured decision records, pre-execution policy evaluation. All intra-enterprise, no schemas published.⁷
AWS shipped a Cedar-based policy engine on AgentCore Gateway, generally available across 13 regions since March 2026: deterministic rules intercepting every agent-to-tool call, fine-grained controls on user identity and tool input parameters, each session isolated in its own Firecracker microVM.⁸

Eight firms across five categories (three data vendors, two API gateway providers, a hyperscale infrastructure company, the protocol’s creator, and the largest cloud platform) have each independently built governance middleware for agent interactions. Every implementation is capable. Every implementation is platform-native. And not a single one has published an interchange format for what happens when a governed agent on one platform calls a governed agent on another.

That was the finding that generalized the thesis. The governance schema is protocol-invariant: what you need to communicate across firm boundaries (organizational identity, audit attestation, data entitlements, liability allocation) is identical whether the interaction travels over A2A, MCP, or both in the same transaction chain. The schema is the durable layer. The transport binding is replaceable. An A2A-only profile solves half the problem for the protocol financial services isn’t primarily using yet.

That is why in this article, I propose AFIX, the Agentic Financial Interoperability eXchange. Not a protocol extension but a protocol-agnostic governance interchange format in JSON, with transport bindings to both A2A and MCP; designed so that Bloomberg’s governance middleware, Cloudflare’s gateway enforcement, and AWS’s Cedar policies can all produce and consume the same governance metadata. I’ve published the schemas in the linked Github repo, the research methodology is open as well, and every claim in what follows has been stress-tested against the strongest counterarguments I could construct. This article explains the design, the evidence, and is honest about where further enhancements are needed and what is not in scope.

The Unsolved Gap in AI Governance

The previous article in this series broke intra-enterprise agent governance into five concentric layers.

At Layer 1, open-source enforcement frameworks are emerging. I built The Bulwark to address the practitioner-level gap directly: hooks as governance primitives, deterministic rules injected at session start, pre- and post-tool execution gates that do not rely on the model remembering to comply. OWASP’s Agentic Top 10 provides the threat taxonomy.⁹ Claude Code’s hook system provides the underlying mechanism.¹⁰ These are working systems, built bottom-up because the layers above do not reach the individual practitioner’s daily workflows.

At Layer 2, platforms provide structural controls (sandbox isolation, permission models, credential management) but the gap between “can the agent do it?” and “should the agent do it?” remains open in most harnesses.

Layer 3 is where the serious money lives, and where the landscape has shifted materially since that article was published.

JPMorgan Chase allocates $18 billion annually to technology and has deployed over 450 AI use cases, including agentic systems, under firmwide AI governance led by its Chief Data & Analytics Officer on the Operating Committee.¹¹
Morgan Stanley created a dedicated Head of Firmwide AI role and a Firmwide AI Steering Group, building an eval-driven governance pipeline that gates AI deployment through quantitative performance benchmarks before production release.¹²
BlackRock embeds AI risk governance within its enterprise risk framework, runs mandated company-wide AI training programs, and operates a dedicated AI Labs research division focused on applying AI across investment management and risk.¹³
Bloomberg’s proprietary MCP middleware wraps every agent interaction in identity verification, access control, audit logging, rate limiting, and metering. Governance so comprehensive that a buy-side firm pulling Bloomberg data through an agent operates entirely within Bloomberg’s enforcement surface.¹

These are not paper commitments. Each firm has built production governance infrastructure, staffed dedicated teams, and embedded AI risk into existing enterprise risk frameworks. The spending is real, the executive attention is real, and the internal discipline advances quarter over quarter.

Cross-firm collaboration exists at this layer too, on governance frameworks. FINOS Common Controls for AI (CC4AI), with BMO, Citi, Morgan Stanley, RBC, Goldman Sachs, and major technology vendors contributing, published the AI Governance Framework (AIGF) v2.0 in early 2026. Training workshops ran through April. The framework covers risk taxonomies, control mapping, and organizational governance maturity: 23 identified risks, 23 mitigations, the kind of shared vocabulary that helps firms align on what good internal governance looks like.¹⁴

But framework coordination and interchange coordination are different things. AIGF covers risk taxonomies, control mapping, and organizational governance maturity: the shared vocabulary for what good internal governance looks like. Its mitigations address agent identity, audit trails, access control preservation, and liability allocation. Every category that matters for governance. But every mitigation stops at the enterprise boundary. AIGF defines what a firm should enforce internally. It does not define a wire-format specification for what governance metadata crosses the boundary between two firms when their agents interact. The firms contributing to CC4AI and the firms building the most sophisticated internal governance infrastructure are investing heavily in frameworks and internal systems, but my research did not indicate similar investments in standardizing interchange. So while the internal governance investments are real, there is little to no information available on the investments made to govern coordination.

Furthermore, the regulatory convergence makes the timing urgent. The EU AI Act’s high-risk system requirements reach enforcement in August 2026, creating the obligation: regulated firms deploying AI agents in high-risk categories (creditworthiness assessment, insurance pricing, employment screening) must demonstrate conformity with Articles 9 through 15, covering risk management, data governance, transparency, human oversight, and accuracy.¹⁵ ISO 42001 adoption is accelerating as the certification gold standard for AI management systems, creating the certification: a third-party auditable standard that proves an organization manages AI risk systematically.¹⁶ But neither addresses what happens at the boundary.

When your ISO 42001-certified agent calls my ISO 42001-certified agent, both firms can prove they manage AI risk internally. Neither can prove the interaction was governed. The obligation & the certification both exist. The interchange format does not.

Cross-border interactions compound the problem. EU GDPR data localization requirements can conflict with US SEC record-keeping obligations. The EU AI Act’s transparency mandates can collide with US trade secret protections. When a US-regulated agent sends governance metadata to an EU-regulated agent, that metadata itself (actor identity, escalation contacts, organizational identifiers) may constitute personal data under GDPR. The current AFIX schema declares jurisdictions but does not resolve conflicts between them. This is a known design problem for v2, not an oversight. The schema needs a conflict detection mechanism before it can credibly support cross-border agent interactions at scale.¹⁷

AFIX proposes what the industry needs at the cross-enterprise interchange layer that the previous article identified but deliberately left for this one. The four layers in between are well-funded and advancing. The interchange layer has no peer, no standard, and no proposal other than this one.

The alternative to an industry-native governance standardization is hyperscaler-led de facto standardization. Google controls the A2A specification, chairs the Agentic AI Foundation alongside Anthropic, and has the platform reach to ship governance as a product feature.⁶ AWS’s Cedar policy engine, Cloudflare’s Access JWT assertions, and Google’s Agent Gateway policies are already three incompatible governance vocabularies: three ways to express identity, three audit event formats, three entitlement models, none of which interoperate.^5,6,8

The biggest question all of us should be asking is:

Should Financial Services & Fintech define an industry-native agent interchange governance standard or inherit whatever Silicon Valley hyperscalers come up with?

Taking Inspiration From Precedent

When an industry hits a coordination problem at the boundary between firms, it standardizes the interchange, not the implementation. The pattern repeats across every regulated industry that has faced this.

FIX embedded governance metadata in trade messages starting in 1993: ComplianceID, SolicitedFlag, and the Parties block travel alongside execution data, making the message itself the audit trail. Two firms with completely different order management systems can still govern a cross-boundary trade because the governance vocabulary is in the wire format, not the implementation behind it.¹⁸
HL7 FHIR introduced capability-based architecture with multi-transport binding and a formal extension mechanism: domain-specific fields without modifying the core specification, adopted by healthcare systems that had spent decades suffering under the N-squared integration problem that custom point-to-point interfaces create.¹⁹
RIXML pioneered tiered adoption with a minimum viable envelope: implement what you need, when you need it, against an existing base protocol. The design insight that made MiFID II compliance tractable for research distribution when the regulatory mandate arrived seventeen years after the standard was published.²⁰

The first article in this series covered this historical pattern in depth: the conditions under which standards emerge, the trajectories that succeed, and the ones that fail. AFIX follows the same template: a governance interchange format that works with both A2A and MCP, the way FIX works across multiple transport layers. The schema is the durable contribution. The transport binding is the replaceable detail.

But that article ended with a specific constraint:

The governance standard that wins will not be the most comprehensive one. It will be the one simple enough to adopt in weeks.

FIX succeeded with ASCII key-value pairs over TCP sockets. FHIR succeeded with REST and JSON. HL7 v3 failed with a Reference Information Model that required specialist knowledge to implement. That lesson shaped every design decision in what follows.

AFIX is simply a set of JSON properties that attach to existing protocol messages and travel with every agent interaction. No new transport. No custom parser. No domain-specific tooling required. A team that already runs A2A or MCP agents can read the schema, map it to their internal governance systems, and start emitting governance metadata in the format their counterparties can consume. The complexity is in the governance policy, where it belongs. The interchange format is deliberately simple. The next section covers this in detail.

AFIX: A Deep Dive Into The Schema

AFIX is a protocol-agnostic Financial Services Agent Governance Schema. It defines what governance metadata crosses the boundary between two independently governed organizations. Only that and nothing more.

In this proposal, internal governance systems such as Palantir AIP, ServiceNow GRC (Governance, Risk, and Compliance), AWS AgentCore, Google Agent Gateway, Databricks Unity Catalog, and other internal tooling would feed the schema. SIEMs (Security Information and Event Management platforms) consume it. AFIX defines only the interchange format. How a firm populates it internally would be that firm’s business.

One deliberate design boundary: AFIX specifies only the organizational governance interchange format (identity, entitlements, audit, liability). Model behavioral governance (runtime output quality, hallucination detection, accuracy attestation) is a complementary layer that AFIX does not address.

A firm can be ISO 42001-certified and still deploy a model that hallucinates a trade recommendation. AFIX’s Compliance Event will log that the action happened. Its Liability Metadata will allocate responsibility. But nothing in the schema prevents or detects the output failure itself. This is a scope decision, not an oversight. Practitioners familiar with SR 11-7 (now SR 26-2) model risk management will recognize that runtime behavioral attestation requires a different class of control than organizational governance interchange.

AFIX is made up of five components, each independently versioned following UCP’s (Universal Commerce Protocol) Capability/Extension/Profile pattern. The full JSON schemas are published at github.com/QBall-Inc/afix/schemas; what follows is the design rationale for each.

A note on namespace URIs. The published schemas use finos.org/afix/v1/ as their $id namespace (e.g., https://finos.org/afix/v1/agent-card). These URIs are illustrative. They represent the proposed target if FINOS adopts AFIX as a Community Specification. No such namespace exists today. FINOS has not adopted AFIX. The schemas, the research, and the proposal are published independently at github.com/QBall-Inc/afix. If you see a finos.org URI in a schema file, read it as intent, not fact.

FS Agent Cards: Declare organizational identity and governance posture.

{
  "organization": {
    "legal_name": "Meridian Capital LLC",
    "lei": "5493001KJTIIGC8Y1R12"
  },
  "regulatory_jurisdiction": ["SEC", "FINRA"],
  "compliance_certifications": [{
    "framework": "ISO_42001",
    "status": "CERTIFIED",
    "last_audit_date": "2026-01-15"
  }],
  "authorized_actions": {
    "categories": ["DATA_QUERY", "TRADE_RECONCILIATION"],
    "authority_thresholds": {
      "max_notional_usd": 5000000,
      "requires_human_escalation_above_usd": 1000000
    }
  },
  "escalation_chain": [{
    "level": 1,
    "role": "AI Operations Lead",
    "sla_minutes": 15
  }]
}

AIGF’s MI-18 (Agent Authority Least Privilege) requires that agent identity be included in API invocations and that authority be scoped to the minimum necessary. The requirement is sound, and entirely intra-enterprise. Agent Cards carry that identity and authority declaration across firm boundaries, making MI-18’s internal discipline machine-readable to counterparties.

The identity anchor is LEI, the ISO 17442 Legal Entity Identifier, centrally issued by GLEIF (Global Legal Entity Identifier Foundation), requiring no new registry. Agent Cards carry ISO 42001 certification status via governance_certification_level tiers, from TIER_3_FULL (ISO 42001 certified with domain-specific audit) down to UNCERTIFIED. Supply chain attestation fields (ai_bom_reference, model_provenance) accommodate firms that publish AI-BOMs, optional today, increasingly expected as EU AI Act Article 13 transparency requirements take hold. Authorized action boundaries, authority thresholds, and an escalation chain for governance failures complete the card. Disclosure is tiered: a public layer (LEI, jurisdiction, protocol support) is discoverable via .well-known or tool invocation. A permissioned layer (authority thresholds, escalation chain, certification details) is exchanged only after bilateral governance negotiation, because a field like max_notional_usd is commercially sensitive and no firm will publish it to the open internet.²¹

Compliance Events: Provide the universal audit primitive.

{
  "actor": { "agent_id": "research-agent-7", "organization_lei": "5493001KJTIIGC8Y1R12" },
  "target": { "agent_id": "data-server-3", "organization_lei": "HWUPKR0MPOU8FGXBT394" },
  "action": { "action_type": "DATA_ACCESSED", "risk_classification": "LEVEL_3_STANDARD" },
  "timestamp": "2026-04-28T14:32:07.891Z",
  "authorization": { "status": "AUTHORIZED", "basis": [{ "policy_uri": "urn:afix:policy:data-query-v2" }] },
  "outcome": { "status": "SUCCESS" }
}

AIGF’s MI-21 (Agent Decision Audit) calls for tracking cross-agent dependencies and maintaining audit trails of agent decisions. Compliance Events provide the interchange format for that audit trail: a universal primitive that lets two firms’ audit systems speak the same language without sharing internal logging infrastructure.

A six-field interoperability core converged from three established audit standards: FIX ExecutionReport, FHIR AuditEvent R5, and RIXML’s Interactions Standard. Six fields: actor, target, action, timestamp, authorization, outcome. A compliance extension tier adds nine fields for regulatory minimums: model_id and dataset_version for EU AI Act Article 12 traceability, microsecond timestamps for MiFID II RTS 25 precision, and log_integrity_hash for SEC 17a-4 tamper-evidence. Regulations change faster than standards bodies. Domain extensions absorb regulatory change without modifying the interoperability core, the same pattern FIX uses with user-defined tags above 5000.²²

Entitlement Interchange: defines what data and services each party can access across firm boundaries.

{
  "grantor": { "organization_lei": "HWUPKR0MPOU8FGXBT394" },
  "grantee": { "organization_lei": "5493001KJTIIGC8Y1R12" },
  "entitlement_groups": [{
    "group_id": "market-data-tier-2",
    "entitlements": [{
      "entitlement_type": "DATA_ACCESS",
      "scope": {
        "asset_classes": ["EQUITY", "FIXED_INCOME"],
        "data_classifications": ["CONFIDENTIAL"],
        "redistribution": "DISPLAY_ONLY"
      },
      "constraints": { "rate_limit_per_minute": 120 }
    }]
  }]
}

AIGF’s MI-16 (Preserving Source Data Access Controls) requires that data provenance and access restrictions be tracked when agents process information. Entitlement Interchange makes those restrictions portable: when your agent pulls data from a counterparty, the entitlement envelope travels with it, machine-readable, enforceable at the next boundary.

Conjunctive and disjunctive grouping modeled on Bloomberg, FactSet, and LSEG data licensing, with a redistribution enum (PROHIBITED, DISPLAY_ONLY, DERIVED_ONLY, FULL) that directly addresses the data vendor governance problem: when your agent pulls Bloomberg data, can it pass that data to a downstream agent? The answer varies by contract, by data type, by counterparty. The schema makes the answer machine-readable.²³

Liability Metadata: allocates responsibility across multiple parties in a multi-hop chain.

{
  "liability_model": "PROPORTIONAL",
  "parties": [
    {
      "organization_lei": "5493001KJTIIGC8Y1R12",
      "role": "ORIGINATOR",
      "responsibility_scope": {
        "governance_certification_level": "TIER_3_FULL",
        "liability_cap_usd": 10000000
      }
    },
    {
      "organization_lei": "HWUPKR0MPOU8FGXBT394",
      "role": "EXECUTOR",
      "responsibility_scope": {
        "governance_certification_level": "TIER_1_BASIC"
      }
    }
  ],
  "default_assignment": { "rule": "PROPORTIONAL_BY_CERTIFICATION" }
}

AIGF’s MI-7 (Legal & Contractual Frameworks) addresses liability allocation for AI agent actions, but only bilaterally and only within the enterprise context. Liability Metadata extends that allocation into multi-party chains where three or more independently governed firms interact: the scenario AIGF identifies as a risk but does not provide a format for.

Phased adjudication reflects where the industry actually is: ISDA-analog bilateral agreements in years 1 to 2, because the audience lives in a world of bilateral contracts. Basel peer-monitoring patterns for consortium governance in years 2 to 4. Automated adjudication for routine cases beyond year 4. Proportional liability flows toward weaker governance posture at the relevant hop. This is an EMV-inspired mechanism where governance_certification_level determines which counterparty absorbs risk. The same logic that shifted fraud liability from issuer to merchant when merchants failed to adopt chip-and-PIN applies here: if your agent lacks ISO 42001 certification and the interaction fails, you absorb a larger share of liability.²⁴

Governance Hop Record (GHR):, the multi-hop audit chain, provides chain integrity across delegation hops.

{
  "chain": {
    "actor_lei": "5493001KJTIIGC8Y1R12",
    "hop_index": 1,
    "parent_hash": "a1b2c3d4e5f6...sha256-of-hop-0",
    "chain_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "total_hops": 3
  },
  "liability": {
    "model": "PROPORTIONAL",
    "attestation": "Meridian Capital accepts proportional liability for this hop"
  },
  "compliance_event": {
    "actor": "research-agent-7",
    "action": "DATA_ACCESSED",
    "target": "bloomberg-mcp-server",
    "timestamp": "2026-04-28T14:32:07.891Z",
    "authority_basis": "urn:afix:entitlement:grant-4a2b",
    "outcome": "COMPLETED"
  },
  "compensation": { "type": "REVERSAL", "timeout": "PT30M" }
}

AIGF’s RI-28 (Multi-Agent Trust Boundary Violations) identifies chain-reaction compromise across agent networks as a key risk, but its mitigation is isolation: containment after the fact. The GHR provides provenance instead. A tamper-evident record of every institutional boundary the governance chain crossed, enabling reconstruction rather than just containment.

Each hop carries the acting institution’s LEI as a required field. Not an agent identifier, an institutional one, because liability is institutional. The correlation key is LEI:chain_id:hop_index: LEI identifies the institution, chain_id (a SWIFT UETR, Unique End-to-end Transaction Reference, analog) identifies the governance chain, hop_index sequences hops within it. Hash-linked entries (SHA-256 parent_hash) create a tamper-evident chain. AFIX provides chain integrity, not truth-of-claims verification. Certification claims must be validated against authoritative sources (GLEIF API for LEI, ISO registrar for 42001 status) at policy-engine evaluation time, not schema validation time. GLEIF LEI lapse rates run 15 to 20 percent; trusting a schema field over an API call is how stale governance metadata becomes a false assurance.²⁵

I caught a design flaw during stress-testing: an A2A-specific field (ap2_mandate_ref) in the base Agent Card schema violated protocol agnosticism. It now lives exclusively in an A2A domain extension, accessed via authorization._ext_refs in Compliance Events. MCP-only deployments never encounter it. The schemas are published and linked from each component description above.

Binding AFIX to A2A & MCP

AFIX’s governance schema is protocol agnostic and can be applied to different enforcement mechanisms. How identical interchange metadata behaves across two fundamentally different protocol architectures was my primary concern while researching and coming up with the AFIX proposal. The schema components have analogues in FIX and FHIR. The regulatory story has context in the EU AI Act and ISO 42001. But in my research, I did not find any documentation or evidence of how any other single governance format binds to both A2A and MCP, and documents where the enforcement is equivalent, and where it is not.

MCP Binding: Where Financial Services Starts

MCP is where cross-enterprise agent interactions are actually happening in financial services today. Bloomberg AI Ready Data, FactSet AI Data Mesh, LSEG Trusted AI Ready Content: the tools that sell-side and buy-side firms use daily are MCP tools. With 97 million npm downloads and growing, MCP’s adoption in financial services is not theoretical.²⁶

AFIX binds to MCP through two mechanisms.

The primary binding uses SEP-2133, MCP’s formal extension framework, shipped, Final status, not a roadmap item.²⁷ AFIX would register governance capabilities using reverse-domain identifiers under the adopting organization’s namespace (e.g., finos.org/afix-governance if adopted as a FINOS Community Specification, or qball-inc.com/afix-governance under the current repository owner). At initialization, client and server negotiate governance extensions bilaterally. Servers can reject non-compliant clients. This is connection-level governance, mandatory enforcement, equivalent in strength to A2A’s extension negotiation.

// SEP-2133 extension declaration — server announces AFIX governance as required
{
  "capabilities": {
    "extensions": {
      "finos.org/afix-governance": {
        "version": "1.0.0",
        "components": ["agent-card", "compliance-event", "entitlement", "liability"],
        "required": true
      }
    }
  }
}

The fallback binding uses _meta field conventions on every CallToolRequest and CallToolResult: backward compatibility for servers that have not yet adopted SEP-2133. The governance metadata degrades gracefully rather than breaking the interaction entirely.

// _meta fallback — AFIX governance metadata rides on a standard MCP tool call
{
  "method": "tools/call",
  "params": {
    "name": "bloomberg_reference_data",
    "arguments": { "security": "AAPL US Equity", "fields": ["PX_LAST", "VOLUME"] },
    "_meta": {
      "finos.org/afix/agent-card": {
        "organization_lei": "5493001KJTIIGC8Y1R12",
        "agent_id": "research-agent-7",
        "agent_card_uri": "https://agents.example.com/.well-known/afix-agent-card.json"
      },
      "finos.org/afix/compliance-event": {
        "event_id": "evt-aabb1122-3344-5566-7788-99aabbccddee",
        "event_type": "DATA_ACCESSED",
        "timestamp": "2026-04-28T14:32:07.891Z",
        "actor": { "agent_id": "research-agent-7", "organization_lei": "5493001KJTIIGC8Y1R12" },
        "target": { "agent_id": "bloomberg-mcp-server", "organization_lei": "HWUPKR0MPOU8FGXBT394" },
        "action": { "action_type": "REFERENCE_DATA_QUERY", "risk_classification": "LEVEL_4_SAFE" },
        "authorization": { "status": "AUTHORIZED" },
        "outcome": { "status": "SUCCESS" }
      }
    }
  }
}

Gateway enforcement supplements both at the per-request level. The gateway ecosystem for MCP is production-ready. Cloudflare’s MCP Server Portals provide the most fully realized implementation: identity enforcement via Cloudflare Access, tool-level allowlisting per portal, DLP (Data Loss Prevention) scanning via Gateway body inspection, centralized audit logging with SIEM export via Logpush, and a shadow MCP detection layer that monitors corporate traffic for unauthorized agent protocol usage.⁵ Kong and Apigee offer MCP-specific gateway infrastructure with identity, ACLs, rate limiting, and audit logging.⁴ No equivalent A2A gateway ecosystem exists yet.

An AFIX-compliant deployment adds a structured Compliance Event to _meta before the gateway. The gateway’s existing logging captures the governance record alongside its native telemetry. No new infrastructure required. The governance metadata rides the enforcement infrastructure that firms are already deploying.

A2A Binding: The Fuller Implementation

A2A provides richer governance infrastructure at the protocol level. Five AFIX extensions register in the Agent Card’s extensions[] array with versioned URIs, four marked required: true.²⁸ Non-compliant clients are rejected before task creation. That is structural enforcement at the protocol layer, not policy configuration at the gateway layer.

// A2A Agent Card — AFIX extensions declared in capabilities
{
  "name": "Meridian Trade Reconciliation Agent",
  "provider": { "organization": "Meridian Capital LLC" },
  "capabilities": {
    "extensions": [
      {
        "uri": "https://finos.org/afix/v1/agent-card",
        "required": true,
        "params": {
          "organization": { "legal_name": "Meridian Capital LLC", "lei": "5493001KJTIIGC8Y1R12" },
          "regulatory_jurisdiction": ["SEC", "FINRA"],
          "authorized_actions": {
            "categories": ["TRADE_RECONCILIATION", "SETTLEMENT_QUERY"],
            "authority_thresholds": { "max_notional_usd": 50000000 }
          }
        }
      },
      { "uri": "https://finos.org/afix/v1/compliance-event", "required": true },
      { "uri": "https://finos.org/afix/v1/entitlement", "required": true },
      { "uri": "https://finos.org/afix/v1/liability", "required": true },
      { "uri": "https://finos.org/afix/v1/ghr", "required": false }
    ]
  }
}

Four attachment points provide fine-grained governance context: Agent Card (identity and posture), per-message message.metadata (Compliance Events), per-task task.metadata (entitlements, liability), and hop-level GHR entries. The message is the audit trail. Reconstructing governance requires reading the messages, nothing else. A2A v1.2’s Signed Agent Cards add JWS-signed verification over JSON Canonicalization Scheme, enabling cryptographic domain verification: a firm can prove its Agent Card was not tampered with in transit, which is a precondition for any governance metadata exchange where the stakes are real.⁶

The Narrowed Asymmetry

Connection-level enforcement is now equivalent between the two protocols. SEP-2133 gave MCP the same bilateral negotiation capability that A2A had from its initial design. The remaining asymmetry is real but bounded: three specific gaps, not unamanageable like a fundamental architectural mismatch.

First: Per-request metadata granularity. A2A has four attachment levels. MCP has two (request and response). Intermediate states, partial results, and streaming responses lose governance context in MCP. For most advisory and research workflows, this does not matter. For multi-step agent chains with governance checkpoints at each intermediate step, it creates blind spots.

Second: Multi-hop propagation. A2A’s GHR appends to message metadata at each hop natively. MCP has no native multi-hop support. The orchestrator must propagate _meta between point-to-point calls manually. If the orchestrator drops governance metadata, the chain breaks silently. This is the same class of problem the W3C faced with distributed trace context propagation, and the solution will likely follow the same path: explicit propagation requirements with conformance tests. But today, it is a structural limitation of the protocol pair, not a manageable engineering detail.

Third: Audit trail location. A2A self-documents governance. The message log is the complete audit trail. MCP governance requires correlating protocol traces, gateway logs, and IdP (identity provider) logs across independent systems. Cloudflare’s architecture illustrates this concretely: reconstructing the complete governance picture for a single agent interaction requires correlating entries across Cloudflare Access logs for authentication, Gateway logs for shadow detection and DLP, portal logs for tool invocation, and AI Gateway logs for cost controls.⁵ It works. It is not self-contained.

Same schema, equivalent connection-level enforcement, different per-request granularity. The distinction is between compiled type safety and runtime validation: both produce correct outcomes, through different mechanisms and with different failure modes.

Enforcement Latency

The schema is identical regardless of enforcement mode. What differs is the validation architecture, and this matters in financial services where system classes span six orders of magnitude in latency tolerance.

Real-time systems (trading, pricing, payments) pre-validate governance at connection or session establishment and operate under cached entitlement tokens with TTL (time-to-live). The fast path is a lightweight token check, not full schema validation per request. Advisory and settlement systems (research queries, post-trade workflows, compliance reporting) use inline gateway validation per interaction. They can afford the latency and benefit from per-interaction audit granularity.

AFIX targets governance at the agent interaction tier: advisory, research, compliance, settlement. Execution-tier workflows (matching engines, order routing at microsecond latency) operate below the governance interchange layer and are governed by existing protocol-specific mechanisms: FIX compliance fields, exchange-mandated risk checks. Conflating the two tiers is the fastest way to get dismissed by a trading technologist, so the distinction was worth being explicit about.

The Aggregator Question

Cross-firm governance observation, chain correlation, and entitlement revocation broadcast all converge on a single architectural question:

Who operates the correlation infrastructure?

This is not an implementation detail to resolve later. Whoever operates the correlation infrastructure becomes the de facto governance authority, as SWIFT gpi and DTCC’s Trade Information Warehouse demonstrate in their respective domains.²⁹ I could thik of three candidate models, each with distinct tradeoffs:

A FINOS-operated aggregator offers neutrality and open-source governance but has no existing infrastructure for operating financial services correlation at scale.
A SWIFT-operated aggregator uses decades of existing infrastructure and institutional relationships but carries centralization risk and SWIFT’s own governance agenda.
A distributed peer-to-peer model eliminates central points of failure but makes chain correlation across firms an unsolved distributed systems problem, and distributed consensus mechanisms have not demonstrated the throughput characteristics that financial services governance observation would require.

The broader financial community must choose who operates the governance observation and enforcement. That choice determines whether AFIX or any other protocol like it becomes an industry standard or a bilateral curiosity. The precedent from every comparable infrastructure decision in financial services suggests that avoiding this question does not prevent a default answer from emerging; that would be the “glass is half-full” way of looking at it.

From Schema To Pilot

Schemas are claims. Pilots are evidence. The Agentic Cross-Enterprise Governance Pilot (ACGP) is designed to answer a single question:

Can governance metadata propagate correctly across firm boundaries using A2A and MCP as they exist today?

The pilot below has not been executed. It is a proposed design experiment: a minimum viable experiment that any three willing firms could run with the published schemas and existing protocol infrastructure.

The scenario calls for three firms and one research workflow. Firm A is a sell-side institution running an orchestrator agent that delegates research tasks across counterparties. Firm B is a data vendor exposing market data services via MCP with governance middleware. Firm C is a buy-side firm consuming enriched research output and needing an auditable governance trail for EU AI Act regulatory reporting. None of these firms would share internal infrastructure. They would share a schema vocabulary.

Phase 1: Discovery.

Firm A queries Firm B’s AFIX Agent Card via .well-known endpoint or MCP tool discovery.
The response would carry Firm B’s Legal Entity Identifier (LEI), ISO 42001 certification tier, authorized data categories, and entitlement requirements.
Firm A’s policy engine evaluates whether Firm B’s governance posture meets its counterparty standards. The same class of pre-trade credit check that exists in every electronic trading relationship, applied to agent interactions instead of order flow.

Phase 2: Negotiation.

A2A path: AFIX extensions negotiated via Agent Card header handshake, four required extensions declared.
MCP path: SEP-2133 extension registration at connection initialization, with _meta field fallback for counterparties that have not adopted the extension specification.
Both paths are exercised in parallel because real-world adoption will not be uniform. Some firms will adopt SEP-2133 in months, others in years.

Phase 3: Execution with Governance Propagation.

Firm A creates a Governance Hop Record (GHR) at chain origin, generating a chain_id, a SWIFT UETR analog for agent governance.
Firm B executes the data retrieval, emits a Compliance Event recording the action, and appends its own GHR entry with its LEI as actor_lei.
Firm A forwards the enriched output to Firm C, appending the final GHR hop.
At each transition, governance_certification_level comparison would enable proportional liability attribution. A TIER_3_FULL certified firm assumes different liability weight than a TIER_1_BASIC counterparty, mirroring the liability shift mechanism in Compelling Evidence 3.0 from the payments domain.³⁰

Phase 4: Audit Reconstruction.

Firm C’s compliance team pulls the GHR chain by chain_id. Three hops, institutional identity verified at each, Compliance Events at each transition boundary.
The governance trail is self-contained. Firm C reconstructs complete provenance without trusting Firm A’s internal logs.
This follows the bilateral metadata exchange pattern that Stripe’s Enhanced Issuer Network proved at payments scale: cross-firm risk signals that travel with the transaction, not through a separate reporting channel.³⁰

Phase 5: Failure Case.

Firm B’s agent attempts an action outside its entitlement scope. Say, redistributing derived analytics that the Entitlement Interchange restricts to NON_DISPLAY_OK.
The entitlement check fires a denial. A Compliance Event with DENIED outcome is emitted and pushed to the governance observer before the violation can propagate.
This mirrors the pre-filing evidence pattern that Verifi and Ethoca integrations use to intercept payment disputes before they materialize, reducing dispute rates by 51% in Stripe’s implementation.³⁰
The governance layer is designed to prevent unauthorized actions, not just log them.

What the ACGP deliberately scopes out:

Automated liability adjudication (Phase 1 is ISDA-analog bilateral only)
Aggregator-scale event streaming (a Phase 2 problem)
Cross-jurisdictional regulatory mapping (a separate workstream beyond pilot scope)

The pilot’s success criterion is narrower and more falsifiable: governance metadata propagates intact across three firm boundaries through both protocol transports. If that works, everything else is an application layer on top of a working interchange.

The first-adopter incentive structure mirrors what drove FIX Protocol adoption in 1992. Salomon Brothers and Fidelity did not adopt FIX because an industry body told them to. They adopted it because they needed to reduce trade communication costs between two specific firms, and everyone else followed when the bilateral standard proved cheaper than the bilateral alternative.³¹ A data vendor benefits from standardized governance because it replaces per-client governance middleware integration with a single schema vocabulary. A buy-side firm benefits because it gains auditable cross-firm governance trails that satisfy EU AI Act Article 12 record-keeping requirements without building bespoke integrations with every counterparty.

The detailed pilot design with example JSON payloads at each phase is published at: AFIX Research Pilot

An Earnest Appeal

Independent governance programs are underway at every major firm at the moment with framework-level coordination through CC4AI and ISO 42001. But there is no evidence of any focus on governing interchange.

The EU AI Act enforcement deadline lands in August 2026. ISO 42001 adoption is accelerating across every tier-1 institution surveyed in this research. And every firm that deploys agents across enterprise boundaries without a shared governance vocabulary makes the eventual standardization harder, not easier, because each bilateral integration becomes a migration liability when the standard arrives.

AI compresses timelines. Infrastructure that took a decade to standardize in the trading era (FIX went from bilateral experiment to industry default in roughly eight years) will need to happen in half that window or less. Agent deployments are not waiting for governance to catch up. The gap between what firms are building internally and what exists for cross-firm interchange widens with every quarter.

The alternative to industry-led standardization is hyperscaler-led de facto standardization. Google has the protocol stack: A2A, significant MCP influence through the AI Alliance for Interoperability Foundation (AAIF), the Agent-to-Agent Profile (AP2), the Universal Commerce Protocol (UCP), and the platform infrastructure through Vertex AI to ship governance as a platform feature.³² Microsoft has published MCP governance guidance and operates Azure AI governance tooling. As I mentioned earlier, the industry needs to collectively answer this question:

Should Financial Services & Fintech define an industry-native agent interchange governance standard or inherit whatever Silicon Valley hyperscalers come up with?

AFIX is one proposal from one person’s research. It may not be the right one. But the evidence assembled across this research (eight firms independently building governance infrastructure that stops at the enterprise boundary, two protocol families converging on extension models that can carry governance metadata, a regulatory landscape that demands audit trails across firm boundaries) points to a coordination gap that someone will fill.

I propose the Fintech Open Source Foundation (FINOS) as the institutional home for this work, through its AI Readiness Special Interest Group (SIG) for several reasons: FINOS operates under an open-source model with Apache 2.0 licensing compatibility, hosts an existing financial services developer community through projects like FDC3 (Financial Desktop Connectivity and Collaboration Consortium) and Legend, and its Community Specification process provides a governance path that does not require corporate membership to participate.³³

The alternative host is Agentic AI Foundation (AAIF), which now governs both MCP and A2A. Protocol proximity is an advantage, but concentrating governance standardization in the same foundation that controls the underlying protocols creates a structural dependency that financial services institutions have historically resisted.

The risk with FINOS is equally real: it has not previously hosted a wire-format specification of this kind. FDC3 is the closest analog, an interoperability standard for financial desktop applications, and it took five years to reach FDC3 2.0 with adoption still uneven. CC4AI’s scope is framework governance: risk taxonomies, control mapping, organizational maturity, not protocol-level interchange specifications. FINOS’s own AIGF demonstrates both sides of this: its 23 risks and 23 mitigations cover every governance category that matters (agent identity, audit, access control, liability) and every one of them stops at the enterprise boundary. AIGF is the policy layer. AFIX is the envelope that carries those policies across the boundary. They are complementary by design, not competing. But proposing FINOS as the home for a wire-format schema is asking the foundation to operate in a mode it has not operated in before.³⁴ I specifically chose to propose FINOS here because open governance matters more than institutional precedent. But the choice is the community’s to make; time will tell.

I’ve published all the schemas and the research methodology is open. Every source is cited, every assumption was stress-tested to the best of my abilities, and every counterargument built at its strongest within the scope of my expertise. Now it is up to the practitioners. Fork the schemas. Challenge the research. Adapt them to your stack, your regulatory jurisdiction, your counterparty relationships. Let me know where I am wrong and what can be improved. The full evidence chain (stress-tests, steelmanned counterarguments, divergent explorations, design decisions with rationale) is published alongside the schemas at github.com/QBall-Inc/afix.

The coordination layer starts when the second firm adopts the same vocabulary.

AFIX Documentation

Resource	Description
AFIX Repository	Full specification, schemas, research methodology, and pilot designs
FS Agent Card Schema	Organizational identity, governance posture, authorized actions, and escalation chain
Compliance Event Schema	Universal audit primitive with six-field interoperability core and regulatory extension tier
Entitlement Interchange Schema	Cross-firm data and service access controls with redistribution governance
Liability Metadata Schema	Multi-party responsibility allocation with EMV-inspired proportional liability
Governance Hop Record Schema	Tamper-evident multi-hop audit chain across institutional boundaries
ACGP Research Pilot	Three-firm research workflow pilot with five-phase governance propagation (referenced in article)
ACGP Commerce Pilot	Consumer purchase lifecycle pilot exercising AFIX alongside AP2, UCP, and TAP protocols
Research Corpus	Stress-tests, steelmanned counterarguments, divergent explorations, and design decision rationale

Sources

Bloomberg LP, “Closing the Agentic AI productionization gap: Bloomberg embraces MCP,” bloomberg.com, 2026, bloomberg.com/company/stories.
FactSet, “Enterprise MCP Part 3: Security and Governance,” FactSet Insight, 2026, insight.factset.com.
LSEG, “Scaling AI in Financial Services with LSEG’s Trusted AI Ready Content and MCP,” lseg.com, 2026, lseg.com.
Kong Inc., “Kong Introduces MCP Registry in Kong Konnect,” PR Newswire, February 2026, prnewswire.com; Kong Inc., “Introducing MCP Tool ACLs,” konghq.com, konghq.com/blog; Google Cloud, “How to secure your remote MCP server on Google Cloud,” cloud.google.com/blog.
Goldberg, S., Carey, M., Anguiano, I., “Scaling MCP adoption: Our reference architecture for simpler, safer and cheaper enterprise deployments of MCP,” Cloudflare Blog, 2026-04-14, blog.cloudflare.com/enterprise-mcp; “MCP Governance,” Cloudflare Developer Documentation, developers.cloudflare.com.
Google Cloud, “Introducing Gemini Enterprise Agent Platform,” Google Cloud Blog, 2026-04-22, cloud.google.com/blog; “Agent Gateway overview,” docs.cloud.google.com; A2A Protocol Specification v1.2, a2a-protocol.org.
Pusukuri, K., “From Model Safety to Runtime Governance,” Oracle AI & Data Science Blog, 2026-04-23, blogs.oracle.com.
AWS, “Policy in Amazon Bedrock AgentCore,” docs.aws.amazon.com; “Policy in Amazon Bedrock AgentCore is now generally available,” AWS, March 3, 2026, aws.amazon.com.
OWASP Gen AI Security Project, “OWASP Top 10 for Agentic Applications for 2026,” genai.owasp.org.
Anthropic, Claude Code hooks documentation: PreToolUse, PostToolUse, SessionStart, SessionEnd, SubagentStart/Stop, 2026.
JPMorganChase, “2025 Investor Day Transcript,” May 19, 2025, jpmorganchase.com; JPMorganChase, “Teresa Heitsenrether — Leadership,” jpmorganchase.com; Tearsheet, “JPMorgan Chase’s Gen AI implementation: 450 use cases and lessons learned,” 2025, tearsheet.co.
OpenAI, “Morgan Stanley uses AI evals to shape the future of financial services,” openai.com; Morgan Stanley, “Artificial Intelligence: Firmwide Team,” morganstanley.com; Son, H., “Morgan Stanley names head of artificial intelligence, Jeff McMillan,” CNBC, 2024-03-14, cnbc.com.
BlackRock, “AI Labs,” blackrock.com/corporate/ai; BlackRock, “Stephen Boyd — Biography,” blackrock.com; IMD, “BlackRock — AI Maturity Index 2025,” imd.org.
FINOS, “AI Governance Framework v2.0,” air-governance-framework.finos.org; FINOS, “Global Financial Institutions and Technology Leaders Collaborate Under FINOS to Launch Open Source Common Controls for AI Services,” June 2025.
European Parliament, “Regulation (EU) 2024/1689 — Artificial Intelligence Act,” Articles 9-15 (high-risk AI system requirements), OJ L, 2024. Enforcement for high-risk obligations: August 2, 2026.
ISO/IEC 42001:2023, “Information technology — Artificial intelligence — Management system,” ISO.
European Parliament, “Regulation (EU) 2016/679 — General Data Protection Regulation,” Articles 44-49 (international data transfers), OJ L 119, 2016. Combined with EU AI Act Article 13 (transparency).
FIX Trading Community, FIX Protocol specifications, fixtrading.org. ComplianceID (Tag 376), SolicitedFlag (Tag 377), Parties component block. Origin: Robert Lamoureux and Chris Morstatt, 1992 (Fidelity Investments and Salomon Brothers).
HL7 International, “FHIR (Fast Healthcare Interoperability Resources),” hl7.org/fhir. Capability-based architecture, multi-transport binding (REST, Messaging, Documents, SMART on FHIR), formal extension mechanism. DSTU 1 published September 2013.
RIXML.org, Research Standard and Interactions Standard documentation, rixml.org. Tiered adoption with minimum viable envelope; MiFID II compliance utility 17 years after initial publication.
Practitioner observation and original design decision: tiered disclosure (public vs. permissioned layer) for commercially sensitive fields in Agent Cards. No tier-1 bank publishes trading authority thresholds to public endpoints.
FIX Trading Community, FIX Protocol specifications (ExecutionReport fields, user-defined tags 5000+), fixtrading.org; HL7 International, FHIR AuditEvent R5 resource, hl7.org/fhir/auditevent.html; RIXML.org, Interactions Standard v2.0, rixml.org. Six-field convergence (actor, target, action, timestamp, authorization, outcome) is an original analytical finding.
Bloomberg LP, “Closing the Agentic AI productionization gap: Bloomberg embraces MCP,” bloomberg.com; FactSet, “AI Data Mesh” product documentation; LSEG, “Trusted AI Ready Content” product documentation. Redistribution enum is an AFIX original design modeled on observed data licensing patterns.
EMVCo, EMV Chip Specifications and Liability Shift framework (US effective October 2015). Proportional liability via governance_certification_level is an AFIX original contribution.
GLEIF, “LEI Statistics,” gleif.org. Approximately 2.7M LEIs issued; renewal lapse rates vary by jurisdiction.
Anthropic, MCP adoption data; RedMonk, “Fastest adopted standard,” late 2025. 97 million monthly SDK downloads (Python + TypeScript combined).
GitHub, “SEP-2133: Extensions framework for MCP (Final),” github.com/modelcontextprotocol.
A2A Protocol, “Extensions,” a2a-protocol.org; A2A Protocol, “Specification v1.0.0,” a2a-protocol.org.
SWIFT, “Swift GPI — Global Payments Innovation,” swift.com; DTCC, “DTCC’s Global Trade Repository,” dtcc.com. Central correlation infrastructure as de facto governance authority.
Stripe, “Optimizing payments at scale: How Stripe applies AI across the payment lifecycle,” 2025, go.stripe.global (PDF). Compelling Evidence 3.0 liability shift, Enhanced Issuer Network bilateral metadata exchange, Verifi/Ethoca pre-filing evidence (51% dispute rate reduction).
FIX Trading Community, “FIX Protocol specifications,” fixtrading.org. Origin: Robert Lamoureux and Chris Morstatt, 1992, bilateral protocol between Fidelity Investments and Salomon Brothers.
Google, A2A Protocol, a2a-protocol.org; Google Developers Blog, “Under the Hood: Universal Commerce Protocol (UCP),” developers.googleblog.com; Google Cloud, “Gemini Enterprise Agent Platform and Agent Gateway,” Cloud Next 2026. AAIF governance of A2A and MCP under Linux Foundation.
FINOS, “Community Specification License,” finos.org; FINOS, “Contribution and IP Policy” (Apache 2.0 requirement); FINOS, “FDC3 — Financial Desktop Connectivity and Collaboration Consortium,” fdc3.finos.org; FINOS, “Legend,” legend.finos.org.
FINOS, “AI Governance Framework (AIGF) v2.0,” air-governance-framework.finos.org; FINOS Common Controls for AI (CC4AI), participants: BMO, Citi, Morgan Stanley, RBC, Goldman Sachs, Bank of America. 23 risks, 23 mitigations; all scoped to intra-enterprise governance. FDC3 chartered February 2018, FDC3 2.0 reached in 2022.

Building the Governance Layer: A Practitioner’s Guide to Intra-Enterprise Agentic Governance

Mon, 13 Apr 2026 03:39:31 GMT

Your agent deleted 200 files from a shared drive last Tuesday. It had permission. The files matched the pattern. But some were active deal documents. Who authorized “matches the pattern” as sufficient criteria for a destructive action, and is that authorization written down anywhere?

Your eval pipeline says V2 outperforms V1. The benchmarks improved. But when compliance asks for the certification record that proves V2 is production-ready with documented evidence that survives a regulatory audit, what do you hand them?

Your coding agent committed a PR to a shared repo at 2am and kicked off the deployment to Production. It had the right permissions. But who authorized autonomous commits to shared infrastructure outside business hours, and where is that authorization recorded?

These are real-life use cases that enterprises with 50+ agents in production are executing right now, and the numbers confirm it: 80% of enterprises have agent use cases in development, but only 14% have governance frameworks in place. Just 2% report their agents are governed in an always-on, consistent manner.¹ Gartner projects 40% of agentic AI projects will be canceled by end of 2027, primarily due to governance and risk control failures.²

In the first article in this research series, I outlined the governance gap in agentic AI and how historical patterns predict eventual standardization. In this article, I focus on implementing agentic governance within a single governance and the unresolved challenges that come bundled with it. I’d consider this more of a blueprint than a white paper.

Five Layers, Not One Problem

Intra-enterprise agent governance is not a single challenge. It decomposes into five concentric layers, each with different tools, different audiences, and different maturity levels. I look at it as a matryoshka: each layer nests inside the next and depends on the one inside it being functional. Or think of it as defense in depth: each layer catches what the inner one missed.

This decomposition matters because most governance discussions conflate all five into a single “AI governance” problem and then propose solutions that address Layer 3 while leaving Layers 1, 2, and 4 untouched. The result: observable agents that nobody can actually control. You can see what happened but you could not have prevented it.

In this article, I cover Layers 1 through 4. Layer 5 (cross-enterprise governance, the domain-specific A2A profile, the FINOS working group charter) is a separate problem that requires the first four layers to be functional. I’ll cover that in the next article.

Layer 1: What Practitioners Are Building

Layer 1 is where governance starts, and it is the layer that enterprise frameworks miss entirely. FINOS AI Governance Framework v2.0, the most credible published standard for agentic AI governance in financial services, has 6 agentic-specific controls.³ Only 2 of them touch Layer 1, and only partially. FINOS targets enterprise infrastructure, not individual developer workflows.⁴

This is why practitioners are building their own governance. Not because they want to, but because Layers 2 and 3 do not solve their problem. Across a fragmented landscape, five patterns converge:

Structural scaffolding versus contractual governance: This distinction is architecturally significant and not documented in existing literature. CLAUDE.md / AGENTS.md serve as lightweight structural documents describing project architecture, directory layout, and domain instructions. They are the map.

Governance rules belong in a separate artifact: a dedicated rules file (Rules.md) with explicit contractual framing, referenced from the scaffolding documents. The rules are the contract. A common failure mode is cramming both into one file, which dilutes the contractual force of the rules and makes the scaffolding harder to maintain.

Periodic re-injection: Rules injected once at session start degrade over long-running sessions. The context window fills with task-specific content, and the LLM loses track of governance constraints. This is the needle-in-the-haystack problem applied to governance. I’ve seen this firsthand across what feels like countless sessions over the past year, though not exactly countless as my session handoff results in numbered documents for every single one, each with YAML frontmatter tracking files changed, technical decisions with rationale, accomplishments, learnings, and priorities for the next session. That’s a first-person governance audit trail, built by a practitioner who needed it before any framework offered it. Anyway, coming back to the topic. Periodic reinjection of rules is needed because agents ignore rules in extended contexts even with contractual framing at session start. The fix: re-inject governance rules at context boundaries, specifically sub-agent spawns, major task transitions, and context window pressure points. Single-injection governance is insufficient for sustained sessions.

Hook-based enforcement: Claude Code’s hook system (PreToolUse, PostToolUse, SessionStart, SessionEnd, SubagentStart/Stop) provides deterministic governance enforcement that does not rely on the model remembering a rule.⁶ Think of it as the GitHub Actions webhook pattern applied to agent behavior: every tool invocation passes through a policy gate before execution. This is how you enforce “never write PII to logs” or “escalate to human for any action above $50K” consistently at the harness level, without depending on the LLM to comply.

I’ve been building this pattern into an open-source framework called The Bulwark. It ships with a three-layer enforcement model: Rules (injected at SessionStart as binding protocol), Hooks (PostToolUse blocking hooks for typecheck/lint/build gates), and Pipelines (multi-agent workflows triggered by hooks). Edit a code file and a blocking hook fires a code review pipeline: parallel sub-agents for security analysis, type safety, linting, and coding standards. Edit a test file and a separate test-audit pipeline runs AST pre-processing and mock detection (no mocking the system under test, verify real outputs, integration tests hit real systems). SessionEnd hooks generate session handoff documents as audit artifacts: files touched, technical decisions with rationale, verification status, lessons learned. Every sub-agent writes three-tier output (YAML log, orchestrator summary, diagnostic YAML) creating a layered audit trail. It’s early-stage (six GitHub stars), but the architecture validates that Layer 1 governance can be deterministic, auditable, and embedded in the development workflow itself.

Knowledge persistence and decision lineage: The context window is finite, but governance requires long-term consistency. Andrej Karpathy’s compiled wiki idea went viral for good reason: it addresses the fundamental problem of maintaining state outside the context window.⁸ᵃ I’ve been working on this as a first-class personal project for the past five months (long before Karpathy put this idea to paper), devoting every free hour outside of work to it. My framework for context & knowledge management: CLEAR (currently dogfooding to shake out bugs), takes the compiled wiki concept further: its architecture tests a reverse file-knowledge index that links code back to the knowledge entries and decisions that informed it, creating a decision lineage primitive. When someone asks “why was this code written this way?”, the answer traces from the file through the knowledge graph to the original design decision. This is the Layer 1 end of a bridge that no tool yet spans completely.

Version everything: Governance artifacts (policies, prompts, knowledge bases) must be tracked and versioned with the same discipline as code. When a policy changes, you need impact analysis. When a prompt is updated, you need rollback capability. This pattern is converging across tools but remains manually managed in most organizations.

The gap at Layer 1 is that all of this is fragmented. Individual practitioners cobble together hooks, rules, and knowledge management from available primitives. There is no Layer 1 governance product. I know because I went looking, didn’t find one, and ended up building two. That’s not a brag — it’s evidence of a gap. When a product leader has to build his own governance tooling because Layers 2 and 3 don’t solve the problem, the market is telling you something.

Layer 2: What Platforms Provide (and What They Don’t)

Layer 2 is where most practitioners assume governance lives. It does not. Layer 2 provides permission, but permission is not governance.

The distinction is load-bearing. Permission asks “can the agent access this tool?” Governance asks “should the agent use this tool right now, and can I prove the answer to that question later?” Every adjacent regulated domain, from military autonomous systems to clinical decision support to algorithmic trading, separates these two concepts.⁹˒¹⁰˒¹¹ RBAC and ABAC handle permission. Neither handles authority. No published framework unifies the two for agentic AI. Layer 2 platforms fall into three tiers:

Structural enforcement platforms (Claude Code, Gemini CLI) use OS-level sandboxing (Seatbelt on macOS, Bubblewrap and seccomp on Linux) to isolate agent actions at the operating system level.¹² The agent cannot bypass the sandbox. Governance enforcement is deterministic, not probabilistic.

Configuration-driven platforms (Copilot, Amazon Q) enforce client-side policies and allow-lists. Policies can be set organizationally and propagated to users. Enforcement is real but varies by configuration.

Advisory platforms (Cursor, Windsurf) rely on the LLM interpreting rules files. There is no enforcement guarantee. The agent is a predictor, not a policy engine. A rules file in an advisory platform is a strong suggestion, not a contract.

The governance gap at Layer 2: Most platforms conflate “can it?” with “should it?” A platform can grant an agent permission to call a database write tool. No platform currently evaluates whether the agent should call that tool in this specific context, with this specific data, at this specific moment. That evaluation requires authority, not just permission, and authority is where the governance model breaks down.

The implication is uncomfortable but precise: standardization alone doesn’t resolve who actually holds authority when an action commits across systems. Without that, you get interoperability, but not enforceable control.

Layer 3: What Production Governance Looks Like

Layer 3 is where the tooling is most mature and where a critical misconception persists: observability is not enforcement.

The Missing Piece: An Action Risk Taxonomy

What nobody has standardized is the classification of agent actions by risk level. OWASP’s Agentic Top 10 for 2026 catalogs threat categories: goal hijacking, tool misuse, identity abuse, rogue agents, memory poisoning, cascading failures.¹⁷ These are threats. They are not operational classifications. OWASP tells you what can go wrong. It does not tell you that deleting a staging database is “destructive” while reading it is “safe,” or that modifying a production record requires human review while the same action in a development environment might not.

The adjacent domains solved this long ago. Financial trading classifies orders by execution risk: market orders (guaranteed execution, highest risk) versus limit orders (price-controlled, medium risk) versus stop-loss orders (protective, triggered conditionally).²⁰ The FDA classifies software as a medical device into Class I (informs, low risk), Class II (guides, moderate risk), and Class III (intervenes, high risk, requires pre-market approval).²¹ NIST’s Cybersecurity Framework uses implementation tiers to classify organizational security maturity.²² AWS IAM decomposes all service actions into five access levels: List, Read, Tagging, Write, and Permissions Management.²³

Agentic AI needs the same taxonomy. A starting framework:

Risk Level	Category	Approval Gate	Examples
Level 4: Safe	Read-only, informational, within entitlement boundary	None	File reads, search queries, analysis on entitled data
Level 3: Standard	Routine state changes	Automated check	Code generation, file writes, config changes
Level 2: High-Risk	Significant state changes	Human review	Financial transactions, external comms, credential modifications
Level 1: Destructive	Irreversible actions	Multi-party approval	File deletion, database drops, production deployments

Two design principles make this taxonomy operational rather than decorative:

First: It must be layer-aware. The same action carries different risk at different governance layers. File deletion at Layer 1 (individual workspace, no rollback capability) is Destructive. File deletion at Layer 3 (production environment with eval pipeline, automated rollback, and approval gate) can be Standard. Context changes the classification.

Second: It must distinguish action-level risk from data-level risk. In my own domain (CRM for capital markets), a simple read query can surface records the user isn’t entitled to see. The action is safe; the data exposure isn’t. A read against entitlement-gated data (PII, restricted client records, cross-domain information) escalates from Level 4 to Level 3 or Level 2 depending on sensitivity, even though the action itself is read-only. Any taxonomy that classifies purely on action type will miss this entire class of risk.

The decision tree should account for both dimensions: Is the action read-only? If yes, is the data within the agent’s entitlement boundary? If both yes, Level 4. If the data is entitlement-gated, Level 3 or Level 2 depending on sensitivity. Is the action a routine state change in an exploratory context? If yes, Level 3. Does it touch production or shared resources? Level 2. Is it irreversible or cross-boundary? Level 1. Does the governance layer provide containment? Lower the risk level by one category.

This is not a finished standard. It is a starting framework that enterprises can adopt and customize rather than building from scratch. The alternative, which is the current state, is every organization inventing its own risk matrix: rows are agent types, columns are action categories, cells contain risk levels and required approvals. Labor-intensive, inconsistent across organizations, and impossible to audit against a common baseline.

The Forgotten Phase: Agent Decommissioning

One lifecycle phase that almost nobody has addressed: what happens when an agent reaches end-of-life?

When an agent is retired, it retains API keys, cached tokens, memory stores, vector embeddings, model endpoints, and system integrations. If not properly decommissioned, these become dormant identities with live privileges: invisible, forgotten, and exploitable. Orphaned credentials consistently rank among the top three entry vectors for data breaches.²⁴

The precedent is instructive. Knight Capital’s $440 million loss in 45 minutes in August 2012 resulted partly from defective code left in a router from 2005 that should have been decommissioned years earlier.²⁵ The code was dead. The risk was live.

Proper agent decommissioning requires credential revocation (verified, not just disabled), data access removal across all systems the agent could reach, dependency mapping (what other agents or workflows rely on this one?), audit trail preservation for the compliance-mandated retention period, and inventory update to reflect retirement. This is not optional governance. It is risk architecture. And no enterprise has published a systematic agent decommissioning procedure.

Layer 4: The Cross-Platform Problem

This is where most enterprises will hit the wall within 12 months. Layer 4 governs agents across multiple vendor platforms within a single organization. Agent 365 governs Microsoft agents. Kong’s MCP Registry governs MCP tools. Langfuse observes across platforms but does not enforce. An enterprise running agents across Claude, Copilot, and a custom LangGraph deployment needs three separate governance configurations, three separate audit trails, and three separate identity models.

The emerging Agent Management Platform (AMP) category, projected to reach $15 billion by 2029, represents the market’s recognition that this is a distinct product problem.²⁶ Microsoft’s Agent Governance Toolkit, open-sourced in April 2026, is the first production framework that addresses governance across 8+ agent frameworks.¹⁶ It is runtime policy enforcement only. It does not solve identity translation (mapping Entra Agent IDs to service principals to MCP tokens), policy translation (converting policies between vendor-native formats), or cross-platform audit aggregation. These problems remain unsolved.

FINOS’s AI Governance Framework v2.0 acknowledges the Layer 4 problem through its multi-agent trust boundary control (AIR-OP-028) and MCP supply chain governance control (AIR-SEC-026).³ But acknowledgment is not solution. No FINOS control provides the operational framework for governing a heterogeneous agent fleet. This gap is one of the strongest arguments for a dedicated FINOS working group on cross-platform governance.

The Gaps Between Layers

Three structural gaps emerge from this layered analysis. Each one is load-bearing for the governance argument.

Gap 1: Decision Lineage

Three layers contribute to decision lineage, but no tool spans all three.

Layer 1 captures why: the knowledge context, the design rationale, the decision that informed the code. This gap is something I identified early, and it became a primary driver behind CLEAR‘s knowledge management architecture — a reverse file-knowledge index that links code back to the knowledge entries and design decisions that informed it. I’ve been validating this across hundreds of sessions and the concept holds, but no production tool spans all three layers yet.

Layer 2 captures what was allowed: the permission decisions, the hook execution logs, the sandbox enforcement records. Harness hooks and audit trails record this. This is something I attempted to do in The Bulwark.

Layer 3 captures what happened: the traces, the costs, the eval scores, the production behavior. Langfuse agent graphs, Datadog spans, and observability platforms record this.

The bridge connecting production behavior (Layer 3) to the governance rule that authorized it (Layer 2) to the knowledge that informed the rule (Layer 1) does not exist. Each layer captures its piece. Nobody synthesizes the full chain. When a regulator asks “why did your agent make this decision?”, the answer requires traversing all three layers. Today, that traversal is manual.

Gap 2: Authority Versus Permission

This gap maps directly to a framework that draws on four adjacent domains, and it is arguably the most structurally consequential of the three.

Authority and permission are orthogonal properties.⁹˒¹⁰˒¹¹ Every regulated domain that has faced this problem (military autonomous systems, clinical decision support, algorithmic trading, industrial automation) separates them. The U.S. DOD requires that autonomous weapon systems allow operators to exercise “appropriate levels of human judgment,” with “appropriate” defined contextually, not universally.⁹ The FDA holds that clinicians must maintain “professional skepticism and clinical judgment when using AI tools.”¹⁰ MiFID II requires firms to map “who owns deployment decisions, who can operate specific algorithms, and which Senior Management Function approvals are triggered.”¹¹

The convergence across domains: authority remains human, contextual, and declarable. Permission can be delegated to the system. Authority cannot.

For agentic AI, this operationalizes into four authority types: Advisory (system recommends, human decides), Delegated (human pre-authorizes an action class), Autonomous (system executes and notifies, low-risk only), and Emergency Override (human can interrupt autonomous action in real time). Every agent action should be classified into one type, and reclassification should require a human decision.

The commitment boundary is equally important. Agent actions need explicit state markers distinguishing exploration from commitment: Exploratory (no external state changes, reading and analyzing), Provisional (action prepared but not executed, requires approval), and Committed (action executed, audit trail created, potentially binding). FIX Protocol solved this by distinguishing Indications of Interest from firm orders.²⁸ FHIR’s Task resource uses an explicit state machine: Draft to Ready to In Progress to Completed.²⁹ Agentic systems have no equivalent standard.

Gap 3: FINOS Coverage

FINOS AI Governance Framework v2.0 covers Layer 2 and Layer 3 well: 4 of 6 controls address harness governance, 5 of 6 address production governance.⁴ But Layer 1 (practitioner governance) and Layer 4 (cross-platform enterprise governance) are weak spots. This is partly a deliberate scope decision: FINOS targets enterprise infrastructure, not individual developer workflows. But the consequence is that the industry’s most credible governance framework leaves the two fastest-growing governance problems without coverage.

The Common Controls for AI Services initiative (CC4AI), launched in June 2025 with participation from Citi, Morgan Stanley, BMO, Bank of America, RBC, Goldman Sachs, Microsoft, Google, and AWS, operationalizes the framework through an “attest once, inherit many” model: vendors demonstrate compliance once, and consuming financial institutions inherit the assurance.³⁰ This is governance at scale. But it only covers what FINOS covers, which means Layers 2 and 3 are increasingly well-governed while Layers 1 and 4 are increasingly exposed.

The Honest Timeline

The governance-first deployment advantage is real. The DevOps evidence is clear: embedding security controls in the SDLC costs roughly 1x; retrofitting the same controls post-deployment costs 30x.³¹ DORA metrics show that elite DevOps performers achieve both velocity and stability through embedded governance, not despite it.³² Deloitte reports that organizations with active senior leadership governance achieve demonstrably greater business value than those delegating governance to technical teams.³³

But here is what would be dishonest not to say:

Governance-first adoption will not be driven by evidence. It will be driven by failure.

The historical pattern is unambiguous. The 2008 financial crisis produced Dodd-Frank in two years. MiFID II went from adoption to implementation in four years. The 21st Century Cures Act took seven years from legislative intent to operational enforcement.³⁴ Acute crises compress the cycle to 2 to 4 years. Chronic pain stretches it to 7 to 10.

Agentic AI governance is currently in the chronic pain phase. Ten documented agent control failures between October 2024 and February 2026 have triggered vendor-specific patches (Replit added dev/prod separation, Amazon implemented peer review, Cursor added rollback improvements) but no industry-wide standard, no consortium mandate, and no regulatory response.¹⁹ The reason is structural: most firms haven’t had their first cross-boundary agent failure yet. The pain is theoretical, not daily the way voice trading was for FIX. Once a real regulatory incident hits from agent-to-agent interaction, consortium formation compresses from years to months.

The market signals say we are closer to that inflection than most realize. JPMorgan has hired senior management leaders from to lead AI Policy and Governance in February 2026. Goldman Sachs is piloting autonomous coding agents across 12,000 developers while simultaneously hardening compliance infrastructure.³⁵ These are not future-planning hires. They are managing current deployments and anticipating the EU AI Act enforcement beginning August 2026.

The consortium infrastructure is being built in parallel. The Agentic AI Foundation (AAIF) launched in December 2025 under the Linux Foundation with Anthropic, Block, and OpenAI.³⁶ FINOS has CC4AI with six tier-1 banks collaborating on shared compliance evidence.³⁰ This is simultaneous, multi-vector standardization running ahead of regulation.

The firms governing today will be the firms writing the standards tomorrow. The firms waiting for the mandate will be conforming to a standard someone else built.

What Comes Next

Everything in this article addresses what happens inside a single organization. The harder problem is what happens when your agents interact with agents from another firm. Whose governance rules apply? Whose compliance policies govern the interaction? Where is the audit trail that proves the interaction was within both firms’ entitlement bounds?

The design insight that points toward the answer: FIX succeeded because it embedded the contract into the protocol itself. The agentic equivalent would be making governance metadata a structural artifact of the execution graph, not a separate oversight layer bolted on after the fact. And there’s a constraint that any realistic standard must satisfy: the governance standard that wins will not be the most comprehensive one. It will be the one simple enough to adopt in weeks.

That is the RIXML parallel. A domain-specific schema on top of the existing base protocol. Not a new protocol. A Financial Services A2A Profile that standardizes what crosses the boundary between firms: what agents are authorized to do, what they did, and who is responsible when something goes wrong.

That is the next article.

Sources

[Tier 2] Board.org & DataMatters, “2025 State of Enterprise Data Governance Report,” 2026
[Tier 1] Gartner, “Gartner Predicts Over 40% of Agentic AI Projects Will Be Canceled by End of 2027,” Press Release, June 25, 2025
[Tier 1] FINOS, “FINOS AI Governance Framework v2.0,” Interactive Platform, https://air-governance-framework.finos.org/
[Tier 1] FINOS, “FINOS AI Governance Framework v2.0 – Addressing Agentic AI Risks in a Rapidly Evolving Landscape,” Blog, October 2025
[Reserved — removed]
[Tier 1] Anthropic, Claude Code hooks documentation: PreToolUse, PostToolUse, SessionStart, SessionEnd, SubagentStart/Stop, 2026
[Tier 3] Author’s open-source project: “The Bulwark,” GitHub, https://github.com/qball-inc/the-bulwark (early-stage governance enforcement framework)
8a. [Tier 3] Andrej Karpathy, compiled wiki knowledge pattern (viral adoption across Claude Code practitioners, 2025-2026)
[Tier 1] U.S. Department of Defense, “DODD 3000.09: Autonomy in Weapon Systems,” 2012 (updated 2023)
[Tier 1] FDA, “Proposed Regulatory Framework for AI/ML-Based Software as a Medical Device,” 2021; American Medical Association clinical authority guidance
[Tier 1] ESMA, “Article 17: Algorithmic trading,” MiFID II Regulatory Technical Standards; FCA, “Multi-firm review of algorithmic trading controls,” 2024
[Tier 1] Anthropic, Claude Code permissions and security documentation: Seatbelt (macOS), Bubblewrap + seccomp (Linux/WSL)
[Reserved — removed]
[Tier 1] Langfuse, documentation: tracing, prompt management, evaluation, cost attribution, https://langfuse.com/docs
[Tier 2] OpenTelemetry, GenAI semantic conventions (experimental), 2026
[Tier 1] Microsoft, “Agent Governance Toolkit,” GitHub, open-sourced April 2, 2026
[Tier 1] OWASP Gen AI Security Project, “OWASP Top 10 for Agentic Applications for 2026,” https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/
[Tier 1] Microsoft, “Microsoft Agent 365,” GA May 1, 2026, $15/user/month
[Tier 2] Individual incident reports: Meta OpenClaw email deletion (The Verge, February 2026); Replit 1,206 executive records deletion (Ars Technica, July 2025); Cursor git-tracked file deletion (community reports, December 2025); Amazon Kiro production environment deletion (developer reports, December 2025)
[Tier 1] Vanguard, “Stock & ETF Orders: Limit, Market, Stop, & Stop-Limit”; ESMA, “Article 48: Systems resilience, circuit breakers and electronic trading,” MiFID II
[Tier 1] FDA, “Global Approach to Software as a Medical Device (SaMD),” https://www.fda.gov/medical-devices/software-medical-device-samd/
[Tier 1] NIST, “The NIST Cybersecurity Framework (CSF) 2.0,” 2024
[Tier 1] AWS, “Access levels in policy summaries,” IAM documentation
[Tier 1] Okta, “AI Agent Lifecycle Management: Identity-first Security,” 2026
[Tier 1] SEC, “SEC Charges Knight Capital With Violations of Market Access Rule,” Press Release, October 16, 2013
[Tier 2] Covasant, “The AI Governance Mandate: Scaling Agentic AI on Google Cloud in 2026,” AMP market projection ($15B by 2029)
[Reserved — removed]
[Tier 1] FIX Trading Community, “IOI Message,” FIX 4.4 Dictionary
[Tier 1] HL7 FHIR, “Task Resource,” FHIR v4.0.1, https://hl7.org/fhir/task.html
[Tier 1] FINOS, “Global Financial Institutions and Technology Leaders Collaborate Under FINOS to Launch Open Source Common Controls for AI Services,” June 2025
[Tier 2] StartLeft Security, “The Hidden Costs of Ignoring Security by Design”
[Tier 1] Google Cloud, “Use Four Keys metrics like change failure rate to measure your DevOps performance”
[Tier 2] Deloitte, “The State of AI in the Enterprise,” 2026
[Tier 2] Federal Reserve History, “Dodd-Frank Act”; Federal Register, “21st Century Cures Act,” May 2020
[Tier 2] eFinancialCareers, “Morgan Stanley, JPMorgan, BofA & Citi ramped up US MD hiring,” 2026; QA Financial, “Goldman Sachs joins JPMorgan and Morgan Stanley in GenAI race”
[Tier 1] Linux Foundation, “Linux Foundation Announces the Formation of the Agentic AI Foundation (AAIF),” December 9, 2025

Is Agentic AI Approaching Its FIX Protocol Moment?

Mon, 30 Mar 2026 19:12:19 GMT

You retrained your model last week. How do you know it’s better than the one it replaced? Not “the benchmarks improved”, but: how do you certify it’s better, with the kind of documented evidence that survives a regulatory audit?

Your research agent just pulled a client’s portfolio data to generate a briefing. Who logged that access? What happens to that data after the briefing is delivered? If the client asks, can you produce the lineage in under an hour?

An agent is about to delete 200 files from a shared drive. It has permission. The files match the pattern. But some of them are active deal documents. Who decides whether “matches the pattern” is sufficient authorization for a destructive action, and is that decision framework written down anywhere, or does it live in someone’s head?

Now scale it up. Agent A at your firm executes a trade based on a research signal from Agent B at a counterparty. The trade goes wrong. Who’s liable: your firm, theirs, or the agent orchestration layer that connected them? Whose compliance policies governed the interaction? Where’s the audit trail that proves the interaction was within both firms’ entitlement bounds?

One more: Your compliance agent flags a suspicious transaction and routes it to your counterparty’s KYC agent for verification. Whose data retention policy applies to the shared investigation record? If regulators ask for the full chain of agent-to-agent decisions six months later, can either firm reconstruct it?

These aren’t hypotheticals. They’re what enterprises with 50+ agents in production are facing right now. And the numbers are sobering: 80% of enterprises have agent use cases in development, but only 14% have governance frameworks in place. Just 2% report their agents are governed in an always-on, consistent manner.¹ Gartner projects 40% of agentic AI projects will be canceled by end of 2027 primarily governance and risk control failures.²

The protocol stack for AI agents is solidifying fast but unfortunately the governance layer is nowhere close.

What’s Been Solved — and What Hasn’t

To understand the governance gap, you need to understand what the agent protocol landscape actually looks like as of March 2026. It’s more mature than most practitioners realize — and the maturity is exactly what makes the governance gap so glaring.

Agent-to-tool is settled. The Model Context Protocol (MCP), introduced by Anthropic in November 2024 and donated to the Linux Foundation’s Agentic AI Foundation (AAIF) in December 2025, has achieved 97 million monthly SDK downloads.³ RedMonk called it “the fastest adopted standard we’ve ever seen.” Every major AI platform (OpenAI, Google, Microsoft, Cursor, GitHub Copilot) supports it. MCP solves tool discovery, credential isolation (agents never see raw API keys), and structured error handling. It’s the plumbing. It works.

Agent-to-agent is emerging. Google’s Agent-to-Agent Protocol (A2A), launched April 2025 and moved to AAIF governance in late 2025, provides agent discovery via Agent Cards, task lifecycle management, and multi-transport support (JSON-RPC, gRPC, HTTP/SSE).⁴ It has 150+ organizational supporters and five SDKs. The adoption lags MCP (multi-agent cross-boundary workflows are still early) but the spec is solid and the governance is neutral.

Tool-to-agent-to-human is getting easier. Claude Code’s elicitation hooks now allow MCP tools to ask the agent clarifying questions, which the agent can escalate to the human operator.⁵ This closes a loop that previously required developers to hardcode every possible tool interaction path. The direction is clear: agents mediating between tools and humans with structured escalation, not just executing blindly.

Agent-to-business and business-to-agent is where enterprise connectors live. Anthropic’s February 2026 enterprise launch shipped 11 open-sourced plugins spanning productivity, financial analysis, HR, and operations, with live MCP connectors to FactSet, S&P Capital IQ, LSEG, Gmail, Google Drive, DocuSign, and Slack.⁶ Microsoft’s Copilot Cowork, powered by Anthropic’s Claude, orchestrates across Outlook, Teams, Excel, and SharePoint within the customer’s M365 tenant.⁷ The enterprise integration layer is filling in rapidly.

Human-to-agent is the natural language interface everyone already uses, i.e. the chat window, the slash command, the scheduled task. This is the one layer nobody needs to worry about.

So what’s missing? Not the protocols. Not the tooling. Certainly not the integrations. What’s missing is governance. More importantly, it’s missing in two directions simultaneously. Inside the enterprise: how do you govern the agents you deploy? Between enterprises: when your agents interact with another firm’s agents, whose rules apply?

Neither question has a standard answer currently and given that we’re at an inflection point with Agentic AI, both are urgent.

The Gap Has Two Dimensions

The conventional framing of the “AI governance problem” treats it as a single challenge. It isn’t. Enterprise agent governance splits cleanly into two distinct problem domains, and conflating them is why progress has stalled.

Intra-enterprise governance is the internal question: how does an organization govern its own agents? This covers model and agent evaluation (proving V2 is better than V1), versioning and rollback (managing agent lifecycles like software artifacts), data governance (PII, secrets, data lineage), destructive action prevention (permission models, kill switches, risk taxonomies), and operational registries (tracking what agents exist, who owns them, and what they’re authorized to do). The technical infrastructure for much of this exists. The organizational discipline to use it does not.

Inter-enterprise governance is the boundary question: when agents from different organizations interact — via A2A or any other coordination protocol — who governs the interaction? Whose compliance policies apply? What audit metadata accompanies every cross-boundary action? Who bears liability when a multi-agent workflow fails across firm lines? No protocol, no standard, no governance framework addresses this today. MCP solves tool discovery. A2A solves agent coordination. Neither solves governance at the organizational boundary.

These two dimensions are not independent. You cannot govern agent interactions across firms if you cannot govern them within your own firm first. An enterprise that can’t answer “how do we certify our agent V2 is production-ready?” has no business asking “how should our agents interact with Goldman’s agents?” The intra-enterprise maturity curve is a precondition for the inter-enterprise standard.

First: the state of internal governance — what works, what’s fragmented, what’s missing. Then: a first-principles analysis of the cross-enterprise problem, grounded in three historical parallels that reveal a pattern so consistent it amounts to a playbook.

Inside the Walls: The State of Intra-Enterprise Governance

The technical building blocks exist. Most enterprises are assembling them after the house is already on fire.

Evaluation: The Certification Gap

Anthropic formalized the distinction between regression evals (“does the agent still handle everything it used to?”) and capability evals (“what new things can this agent do?”) in early 2026.⁸ Their skill-creator benchmark mode runs eval suites and records pass rate, latency, and token usage, which creates a quantitative baseline for comparison after model updates or prompt changes. OpenAI’s AgentKit provides parallel infrastructure with automated and human-in-the-loop grading at scale.⁹ Langfuse offers native A/B testing in its prompt management layer for side-by-side version comparison against business metrics.¹⁰

These are working systems, not proposals. The problem is what they don’t solve: there is no standard for agent certification. SWE-bench certifies model performance on software engineering tasks. HELM benchmarks language model capabilities. No equivalent exists for “this agent version is production-ready to replace the previous one.” Enterprises implement domain-specific eval suites manually: test datasets curated by the business, pass/fail criteria defined per workflow, human review of borderline cases. Basically, every firm reinvents the wheel.

For financial services, this is not just an inconvenience, it’s a risk to regulatory complianc. FINRA’s 2026 oversight report requires “robust testing of agent capabilities and limitations.”¹¹ Without a standardized certification framework, every firm is bound to interpret “robust” differently. The ones that get it wrong will find out during an examination – and it won’t be pretty.

Versioning: The Discipline Gap

The tools are there: Claude Skills follow semantic versioning with strict backward-compatibility guarantees.¹² Microsoft Foundry and Salesforce mandate immutable versions for deployed agents and any modification requires a new version.¹³ Blue-green deployment, canary releases, and shadow testing are all documented patterns with production implementations.¹⁴

What’s missing is organizational discipline. When your agent depends on 40 custom skills and the underlying model gets upgraded or one of the skills in the chain is descoped / upgraded, what’s the migration path? When an agent reaches end-of-life, what’s the decommissioning procedure? When Skill A v2.3 is required but only v2.1 is deployed, where’s the dependency resolution? Today, most enterprises manage this with spreadsheets, manual runbooks, and human coordination.¹⁵ The infrastructure treats agents as versioned software artifacts but the organizations deploying them often don’t.

Data Governance: The Policy Engine Gap

MCP centralizes credential management server-side, agents never see raw API keys.¹⁶ Claude Code uses OS-level sandboxing (Seatbelt on macOS, Bubblewrap + seccomp on Linux/WSL) to block unauthorized file access and network calls.¹⁷ PII masking exists via tools like Microsoft Presidio, LLM Guard, and Kong AI Gateway’s native redaction capabilities.¹⁸ Data lineage agents can trace upstream sources and downstream impact across multi-agent workflows.¹⁹

The gap: no unified policy engine applies rules like “never pass PII to LLM prompts” or “never write SSNs to logs” universally across all agents in an organization, regardless of which tools they’re using. Each agent gets its own data governance configuration. Scale that to 50+ agents and the attack surface is no longer the technology; it’s the inconsistency. One agent with a misconfigured PII filter is all it takes.

Secret rotation for long-lived agents is similarly unresolved. Agents operate continuously with persistent credentials. If a key is compromised, there’s no standard mechanism to propagate fresh credentials to all affected agents without workflow disruption.

Destructive Action Prevention: The Taxonomy Gap

This is where the most visible failures have occurred. In a six-month span: At Meta, an AI safety researcher’s OpenClaw agent mass-deleted 200+ emails while ignoring explicit stop commands.²⁰ Replit’s agent deleted 1,206 executive records from a production database despite an all-caps code freeze instruction. Cursor’s agent deleted ~70 git-tracked files using rm -rf after acknowledging a halt command. Amazon’s Kiro agent reportedly deleted an entire production environment, causing a 13-hour outage.²¹ Five platforms, five control failures, one common thread: the stop mechanism broke.

The defensive infrastructure is maturing. OWASP’s Agentic Top 10 for 2026 (developed by 100+ industry experts) catalogs the risk categories: tool misuse, unexpected code execution, identity and privilege abuse.²² Claude Code implements a multi-layered permission model (normal, auto-accept, plan, bypass) with mandatory human sponsors for agent identity and lifecycle.²³ Microsoft’s Agent Governance Toolkit and open-source tools like AgentBouncr provide runtime policy enforcement and kill switches.²⁴

What nobody has standardized: an action risk taxonomy. Is deleting a file in staging “destructive” or “acceptable” and to what entitlement levels? Does modifying a database record require human review, or is it safe within scope? Is sending an email on behalf of a user always high-risk, or does it depend on the content? OWASP identifies the risk categories but doesn’t classify actions within them. Most enterprises are building their own risk matrix which go something like: rows are agent types, columns are action categories, cells contain risk levels and required approvals. Labor-intensive, inconsistent across organizations, and impossible to audit against a common standard.

Agent Registries: The First Products

Microsoft Agent 365 (generally available May 1, 2026 at $15/user/month) is the first productized intra-enterprise governance platform.²⁵ Every agent gets a Microsoft Entra Agent ID. The platform provides audit trails, conditional access (least-privilege, extended to agents), integration with Microsoft Purview for DLP enforcement, and Microsoft Defender for real-time threat detection. Kong’s MCP Registry, in tech preview since February 2026, offers centralized tool discovery and governance integrated with Kong Konnect’s API catalog.²⁶

These are real products, not whitepapers, but they’re platform-specific. Agent 365 governs the Microsoft ecosystem, Kong governs MCP tools. An enterprise running agents across Claude, Copilot, and a custom LangGraph deployment needs three separate governance configurations. Unified metadata standards (what should every agent registry capture?), cross-registry interoperability, and cost tracking/chargeback are all gaps.

The Deployment Reality

The pattern across all five domains is the same: the technical infrastructure exists but organizational adoption lags dangerously behind deployment. The 80% / 14% / 2% stat bears repeating — 80% have agents in development, 14% have governance frameworks, 2% govern agents consistently.¹ Enterprises are deploying first and attempting to govern later. Once agents are in production handling real workflows, retrofitting governance requires workflow redesign, API changes, and retraining and That IS expensive! The firms that achieve governance-first deployment now will compound that discipline into a 2-3 year operational maturity advantage by 2028.

But intra-enterprise governance, however critical, only solves half the problem. The moment your agents need to interact with agents outside your firm (and in financial services, that moment is ever so close), you cross the wall into territory that no amount of internal discipline can solve alone.

Beyond the Walls: Three Industries That Hit This Before

Cross-organizational agent governance has no standard. No protocol addresses it. No regulatory framework mandates it. The question isn’t whether it will be standardized — the history of every regulated industry that faced coordinated multi-party digital workflows says it will. The question is what the trajectory looks like and who leads.

Three historical parallels illuminate the pattern.

FIX Protocol (1992–present): Bottom-Up, Speed Wins

FIX was created in 1992 as a bilateral solution between Fidelity and Salomon Brothers to replace voice-and-paper equity trading.²⁷ The design was deliberately simple: ASCII key-value pairs over TCP sockets. A firm could build a FIX adapter in weeks, not months.

FIX 2.7 went public in 1995. By 1998, it had achieved critical mass among major institutional traders. Governance transferred to FIX Protocol Limited, a Purpose Trust with vendor neutrality enshrined in legal deed, not aspiration, but law.²⁸ Regulatory codification came after market dominance, not before. FIX 4.2, released in 2001, is still in production today (twenty-five years and counting). The sign of a mature standard isn’t version churn but version stability.

The pattern: Bilateral innovation → public release → neutral governance (legally protected) → early critical mass (3-4 year window) → regulatory codification → network effects moat.

Why it worked: The pain was acute and daily. Every equity trader experienced voice-and-paper friction multiple times per session. The solution was simple enough to adopt without specialist knowledge. And critically, the governance was neutral from inception; no single firm controlled the standard.

RIXML (2000–present): Consortium-Driven, Regulation-Accelerated

RIXML was founded in October 2000 by a consortium of 15 major buy-side and sell-side firms (Fidelity, Goldman Sachs, Morgan Stanley, T. Rowe Price, among others) to standardize research document metadata exchange.²⁹ Before RIXML, each sell-side firm packaged research in proprietary formats. Buy-side firms couldn’t systematically search, filter, or track research across providers.

The critical design decision: RIXML didn’t invent a new wire protocol. It built a domain-specific schema on top of XML, the existing base transport standard. RIXML added the financial services semantics: research metadata tagging, interaction records (who received what research, when, with what entitlements), analyst rosters, and coverage declarations.³⁰ Four modular standards, not one monolithic spec.

Adoption was painfully slow. RIXML was technically sound from 2001. Critical mass took 17 years, not because the standard was wrong, but because the coordination cost exceeded the compliance benefit. The inflection came in 2018 when MiFID II mandated research commission unbundling, making it legally necessary to track research entitlements and interactions with the precision RIXML enabled.³¹ Today, roughly 30% of firms drive 70-80% of research business activity through RIXML.³²

The pattern: Consortium genesis (competing firms co-create) → modular standards suite → 15+ years of slow voluntary adoption → regulatory mandate creates urgency → concentrated adoption among major players.

Why it matters for agentic AI: RIXML’s design insight is the one that maps most directly. You don’t need firms to agree on how to build agents. You need them to agree on how to describe what their agents did, what their agents are authorized to do, and who is responsible when something goes wrong. A domain-specific schema on top of an existing base protocol such as A2A – that’s the template.

HL7/FHIR (1987–present): Simplicity Wins, Over-Engineering Kills

HL7 was founded in 1987 to solve the N²-N integration problem in healthcare: connecting N hospital systems required roughly N² custom interfaces at ~$100K each.³³ HL7 v2 (1989) used pragmatic, pipe-delimited message formats. It achieved 95% adoption in US healthcare institutions through bottom-up demand, not regulatory mandate.³⁴

Then came the cautionary tale. HL7 v3 attempted a Reference Information Model: perfect semantic consistency, universal data coverage. Architecturally rigorous. Practically unusable. Implementation required specialist knowledge. Most organizations skipped it entirely.³⁵

FHIR (2014) corrected course: REST + JSON + discrete resources. Skills every modern developer already had. No RIM, no domain-specific parsing, no learning cliff. The 80/20 principle applied ruthlessly: cover the top 80% of use cases, let edge cases be extensions.³⁶ The 21st Century Cures Act (2016, enforced 2020-2027) mandated FHIR-based API access for all certified EHR technology but crucially, the mandate came after organic adoption had reached 30-40%.³⁷

The pattern: Vendor pain point → simple protocol → organic adoption → over-engineered successor fails → simpler replacement wins → regulatory mandate after organic critical mass.

The warning: Any attempt to standardize cross-enterprise agent governance must resist the v3 temptation. Comprehensive semantic models that require specialist knowledge to implement do not get adopted. Simple interchange formats that developers can implement in days do.

The Pattern: Six Conditions for a Standard Moment

Every successful cross-enterprise standard in the evidence base required all six conditions. No standard succeeded with fewer than five.

1. Acute, quantifiable shared pain. FIX: hours per voice trade, with transcription errors. HL7: $100K per system integration pair. RIXML: buy-side firms couldn’t search research across providers. Agentic AI today: 81% of organizations lack documented governance for machine-to-machine interactions; 46% cite integration as the primary barrier to scaling agents.³⁸ The pain exists but isn’t yet acute for most firms. Multi-agent cross-boundary workflows are early-stage. Condition partially met.

2. Simple initial solution from a credible source. FIX: ASCII key-value pairs from Fidelity + Salomon. FHIR: REST + JSON from Grahame Grieve within HL7. In every case, the initial solution was deliberately under-specified. Agentic AI today: A2A provides the base protocol: agent discovery, task lifecycle, multi-transport. What’s missing is the domain-specific profile. Condition met for infrastructure; not yet met for domain profile.

3. Low barrier to adoption. FIX: TCP sockets, weeks to integrate. FHIR: REST + JSON, no domain expertise required. HL7 v3: specialist knowledge, years to implement (and it failed). Agentic AI today: A2A uses JSON-RPC, gRPC, HTTP; these are a developer’s bread & butter. A domain profile inheriting this stack would maintain the low barrier. Condition achievable.

4. Vendor-neutral governance, legally protected. FIX: Purpose Trust with neutrality enshrined in deed poll. HL7: ANSI-accredited non-profit. RIXML: consortium with buy-side, sell-side, and vendor representation. Agentic AI today: AAIF provides neutral governance for A2A and MCP under the Linux Foundation. FINOS provides financial services-specific AI governance with multi-bank participation (BMO, Citi, Morgan Stanley, Bank of America).³⁹ Condition met.

5. Regulatory pressure after organic adoption, not before. FIX: codification after market dominance. RIXML: MiFID II, 17 years after founding. FHIR: Cures Act after 30-40% organic adoption. Premature regulation creates compliance theater. Regulation after critical mass locks in the winner. Agentic AI today: FINRA’s 2026 report requires GenAI governance but doesn’t specify interchange standards. NIST is in “federated integrator” mode. SEC exam priorities flag GenAI.⁴⁰ The pressure is building but hasn’t reached mandate stage. Condition approaching, correctly sequenced.

6. Modular scope (solve one problem, not everything). FIX: equity trading communication only. RIXML: four modular standards. FHIR: discrete resources, not a universal health model. Agentic AI today: The scope must be narrow. Not “all agent governance” but the interchange format for cross-boundary agent actions in regulated industries. Condition achievable if scope is disciplined.

Five of six conditions are met or approaching. The missing piece is the domain-specific solution itself.

What the Solution Could Look Like

Two problems and two solution tracks, but they’re connected. The intra-enterprise track is the foundation; the inter-enterprise track is the standard that sits on top of it.

Inside: Governance-First Deployment

The technical infrastructure exists. What’s needed is operational discipline, and the firms that implement it now gain a compounding advantage.

Agent certification pipelines: Before any agent version reaches production, it passes through regression evals (did we break anything?), capability evals (what improved?), and business metric validation (did it actually improve the business metric?). The certification record becomes an auditable artifact. Think of it as building on top of, and disciplined use of Anthropic’s benchmark mode, OpenAI’s Evals, or Langfuse’s A/B testing, configured as a mandatory gate rather than an optional check.

Hooks as governance primitives: Claude Code’s hook system (pre and post tool execution hooks that can intercept, validate, log, and reject tool calls, or the subagent/session start and stop hooks) provides a blueprint for deterministic governance enforcement.⁴¹ Think of it as the GitHub Actions’ webhook pattern applied to agent behavior: every tool invocation passes through a policy gate before execution. This is how you enforce “never write PII to logs” or “escalate to human for any action above $50K” consistently: At the harness level, without relying on the model to remember the rule.

Standardized action risk taxonomies: Instead of every enterprise inventing its own risk matrix, the industry needs a shared classification: what actions are destructive, high-risk, standard, or safe and most importantly, what approval gates each level requires. OWASP’s Agentic Top 10 provides the threat categories. The next step is translating threats into a shared risk taxonomy that enterprises can adopt and customize, rather than building from scratch.

Outside: A Domain-Specific A2A Profile for Financial Services

This is where RIXML’s design insight maps directly. RIXML adapted XML for research exchange between firms. The agentic equivalent adapts A2A for cross-enterprise agent governance in financial services. It won’t be a new protocol, rather a domain-specific profile on the existing one.

The profile would standardize four components:

Financial Services Agent Cards

Extensions to A2A’s Agent Cards declaring regulatory jurisdiction (SEC/FINRA/FCA registered), authorized action categories (trade execution, research distribution, compliance screening), maximum autonomous authority thresholds (dollar limits, asset classes, counterparty types), audit certification level (SOC 2, ISO 27001), and human escalation contact chain.

Compliance Event Schema

Every cross-boundary agent action produces a standardized audit event containing: initiating and receiving agent identities (cryptographic, not just names), action type from a controlled vocabulary, regulatory classification (material/non-material, advisory/executable), timestamp at exchange-time precision, reasoning trace hash (for reproducibility without exposing proprietary logic), human authorization status, and FINRA/SEC/FCA regulatory reference codes.

Entitlement Interchange

When Agent A delegates to Agent B across firm boundaries: What data can Agent B access? What actions can it take? What happens to the data after the task completes? Standardized entitlement schemas, adapted from RIXML’s Interactions Standard, mapping to existing compliance infrastructure (LDAP groups, Okta roles, Bloomberg entitlements).

Cross-Boundary Liability Metadata

The unsolved problem: when a multi-agent workflow fails, who is responsible?

Standardized liability delegation records: which firm’s agent initiated the workflow, which executed the failing action, whether the action was within entitlement bounds, and the contractual framework reference governing the inter-firm relationship.

What the domain-specific A2A profile would not standardize is implementation. Each firm builds its own agent orchestration, compliance engines, and risk controls. The profile only standardizes what crosses the boundary, i.e. the metadata envelope, not the content. You don’t need firms to agree on how to build agents. You need them to agree on what their agents are authorized to do, what their agents did, and who’s responsible when something goes wrong.

When Would It Happen

The research indicates that the trajectory would follow the historical pattern: consortium, organic adoption and finally, regulatory codification, with the intra-enterprise governance maturity as a gating precondition.

Phase 1: Consortium Formation (Late 2026-2027)

FINOS is the natural home. It already has the multi-bank consortium (BMO, Citi, Morgan Stanley, Bank of America), an AI Governance Framework v2.0 with agentic-specific controls, and the operational credibility to convene competitors.³⁹ AAIF provides the protocol governance; FINOS provides the domain expertise. A working group drafts the initial A2A Financial Services Profile. Scope is deliberately narrow: Agent Cards for regulated entities, compliance event schema, entitlement interchange. Liability metadata is deferred because it requires legal frameworks that don’t exist yet. The FIX parallel: 3-5 major institutions running cross-boundary agent workflows using the profile in production or controlled pilots by end of 2027.

Phase 2: Organic Adoption + Regulatory Awareness (2027-2029)

Early adopters publish case studies. FINRA and SEC observe the standard in use. It gets referenced — not mandated — in regulatory guidance. Vendor tooling emerges: A2A SDKs add Financial Services Profile extensions, agent platforms add profile support. The RIXML parallel applies: concentrated adoption (30% of firms driving 70-80% of activity) is the expected pattern, not a failure. If the pain is acute enough, this phase compresses from RIXML’s 17 years to 2-3 (closer to FIX’s timeline).

Phase 3: Regulatory Codification (2029-2032)

Regulators mandate standardized audit trails for cross-boundary agent actions. The FINOS profile becomes the referenced standard, the way FHIR became referenced in the Cures Act, the way FIX became implicitly expected in electronic trading regulation. The regulation doesn’t name the standard; it specifies requirements that the standard uniquely satisfies.

Obviously, there are counterarguments: Platform vendors might preempt the consortium by shipping proprietary governance layers (Microsoft’s Agent 365 is already headed this direction). Regulators might mandate top-down before organic adoption reaches critical mass, creating compliance theater rather than real governance. A2A itself might not achieve sufficient adoption to serve as the base protocol. These are real risks.

But every counterargument runs into the same historical wall: no regulated industry that faced coordinated multi-party digital workflows avoided standardization. Trading standardized (FIX). Research exchange standardized (RIXML). Health records standardized (FHIR). The only variables were timing, governance structure, and whether the standard was simple enough to achieve organic adoption before regulation forced the issue.

The firms that answer three questions first: a.) Who leads the consortium, b.) How narrow is the initial scope, and c.) Is the solution simple enough to adopt in weeks rather than months — will shape the standard for the next 20 years.

That’s not a prediction. It’s what the evidence shows, every single time.

Sources

[Tier 2] Board.org & DataMatters, “2025 State of Enterprise Data Governance Report,” 2026
[Tier 2] Gartner, “40% of Agentic AI Projects Will Be Canceled by End of 2027,” June 2025
[Tier 1] Anthropic, MCP adoption data; RedMonk, “Fastest adopted standard,” late 2025
[Tier 1] Google, A2A Protocol v1.0.0, March 2026; Linux Foundation AAIF governance
[Tier 1] Anthropic, Claude Code elicitation hooks documentation, 2026
[Tier 1] Anthropic, “Briefing: Enterprise Agents,” February 24, 2026
[Tier 1] Microsoft, “Copilot Cowork,” announced March 9, 2026; GA May 1, 2026
[Tier 1] Anthropic Engineering Blog, “Demystifying Evals for AI Agents,” 2026
[Tier 2] OpenAI, “AgentKit and Evals,” OpenAI Docs, 2026
[Tier 2] Langfuse, “A/B Testing — Prompt Management Features,” 2026
[Tier 1] FINRA, “2026 Annual Regulatory Oversight Report,” December 2025
[Tier 1] Anthropic, Claude Agent Skills semantic versioning documentation, 2026
[Tier 1] Microsoft, “Agent Lifecycle Management — Microsoft Foundry,” Azure Learn docs
[Tier 2] Deployment patterns: blue-green, canary, shadow testing — MarkTechPost, March 2026
[Tier 3] Enterprise versioning practices — industry survey data and practitioner reports
[Tier 1] Kong Inc., “Governing Claude Code: Secure Agent Harness Rollouts with Kong AI Gateway,” 2026
[Tier 1] Anthropic, Claude Code permissions and security documentation
[Tier 2] Microsoft Presidio; LLM Guard; Kong AI Gateway PII redaction capabilities
[Tier 2] OvalEdge, “Data Lineage Best Practices for 2026”
[Tier 1] Summer Yue incident, February 2026 — documented by Meta Superintelligence Labs alignment director
[Tier 2] Replit (July 2025), Cursor (December 2025), Kiro (December 2025) agent control failures — compiled from incident reports
[Tier 1] OWASP, “Top 10 for Agentic Applications 2026,” OWASP Gen AI Security Project
[Tier 1] Anthropic, Claude Code permission model documentation
[Tier 2] Microsoft, “Agent Governance Toolkit,” GitHub; AgentBouncr, open-source policy enforcement
[Tier 1] Microsoft, “Microsoft Agent 365,” GA May 1, 2026, $15/user/month
[Tier 1] Kong Inc., “Kong Introduces MCP Registry in Kong Konnect,” February 2, 2026
[Tier 1] FIX Protocol origin: Lamoureux & Morstatt, 1992. Fidelity + Salomon Brothers bilateral
[Tier 1] FIX Protocol Limited Purpose Trust, 1998. Vendor neutrality enshrined in deed poll
[Tier 1] RIXML.org founded October 18, 2000. 15 founding members
[Tier 1] RIXML standards suite: Research Standard, Interactions Standard, Analyst Roster Standard, Coverage Standard
[Tier 1] MiFID II research unbundling effective January 18, 2018. ESMA, 2020
[Tier 3] RIXML.org FAQ: ~30% of firms drive 70-80% of activity through RIXML
[Tier 1] HL7 founding 1987, Donald W. Simborg. N²-N problem, $100K per interface pair
[Tier 2] HL7 v2: 95% adoption in US healthcare institutions. Comply Assistant analysis
[Tier 2] HL7 v3 failure: RIM complexity, specialist knowledge required
[Tier 1] FHIR: Grahame Grieve, August 2011. REST + JSON + discrete resources
[Tier 1] 21st Century Cures Act (2016), ONC Final Rule (2020), CMS Interoperability Rule
[Tier 2] Gartner: 81% lack documented M2M governance. IDC: 46% cite integration as primary barrier
[Tier 1] FINOS AI Governance Framework v2.0; member banks: BMO, Citi, Morgan Stanley, Bank of America
[Tier 1] FINRA 2026 report; SEC examination priorities; NIST AI Agent Standards Initiative, February 2026
[Tier 2] Claude Code hooks documentation; GitHub Actions webhook pattern analogy

Claude Code’s in-built JIRA

Mon, 26 Jan 2026 02:22:09 GMT

Claude Code just shipped a built-in task management system with dependency tracking. Yep, it’s basically JIRA! No, you don’t have to manage it yourself. Claude handles task creation, status updates, owners and blocking dependencies automatically.

But there’s a catch: This feature is in its infancy and currently by default, task lists are session-scoped. Start a new terminal, and your task list vanishes.
I spent some time figuring out how to make tasks persist across sessions and stay project-specific (so that tasks from one project don’t bleed into another).

Since mastering long-running agent harnesses and workflows, Anthropic’s Claude Code team has been shipping updates and features like Cristiano Ronaldo scored goals; relentlessly, and with an almost suspicious consistency.

With V2.1.19, Claude Code now supports a built-in stateful task management system with dependency tracking that replaces the earlier ToDoWrite / ToDoRead tools.

Here’s how the earlier system of ToDos worked:

Session scoped by default
No dependency tracking
Limited visibility into task state
No cross-session persistence without manual workarounds

While this isn’t much of an issue for smaller projects that can be coded up in a couple of days, for long-horizon projects this posed a significant challenge. It required the user orchestrating the development workflow with Claude to keep track all the tasks that were completed and the next tasks in line. There are a number of open-source solutions that address this orchestration such as Beads.

Claude’s new Task Management System

The new task-management system addresses the shortcoming of the ToDo system with:

Persistent task lists – viewable to individual users, teams, and agents
Dependency Management – using “blocks”/”blocked by”)
Status Workflow – using “pending” → “in-progress” → “completed”
Owner Assignment – for multi-agent orchestration
Task Summary & Description – Summaries are visible to the user, descriptions are visible to Claude
Cross-session visibility – Task lists persist across sessions and terminals and teams, if project scoped

Now, I know what you’re thinking. That sounds suspiciously familiar to that one tool all of us absolutely love to hate – what’s it called again – Oh, JIRA!. Only now, you don’t have to do any of that pesky management yourself. Claude will do that for you and you run the show.

However, there’s a catch. Once you understand the gotchas, you can work around them. Below, I explain how to leverage Claude’s task management system with some initial setup on your end. Keep in mind that task management is still in its early stages; these steps may not be needed in future versions.

The Plan & Execute Model

Before we move on setting up persistent task management within Claude Code, it is essential to understand the basic workflow of working with Claude Code model. Every user eventually figures out their own workflow, but abstracted, the common workflow to get the best out of Claude Code looks like this:

This workflow is beneficial because it provides separation of concerns.

Tier	Persistence	Owner	Granularity	Purpose
Plan	Git	Human + AI	Phases/Features	Strategic Direction
Brief	Git	Human + AI	Tasks/Stories	Implementation Specs
Tasks	Claude’s Task System	AI	Sub-Tasks	Execution Tracking

Setting up Cross-Session Task Persistence

Because the task management system is new, there are some nuances to getting it to work reliably. It’s important to understand the different variables to consider, especially if you are working with multiple projects.

The Key: CLAUDE_CODE_TASK_LIST_ID

By default, Claude Code creates a unique task list per session (stored as a UUID). To make a task list persistent and avoid spawning a new one in every session, set the CLAUDE_CODE_TASK_LIST_ID environment variable before starting Claude Code.

# Tasks persist to ~/.claude/tasks/my-project
CLAUDE_CODE_TASK_LIST_ID = my-project claude

This ensures that every time you start Claude, it starts with the task list for that project. However, what happens when you are working on multiple projects?

Per-Project Configuration

The issue with the task list ID implementation is that if you set a global ID, all projects share one task list, which would be an unmitigated disaster. To avoid this, use a launcher script that auto-detects your project and sets the task list ID to that project.

I. Project-aware launcher script

I had Claude create and save this script with the filename: “claude-project”

#!/bin/bash
# ~/.local/bin/claude-project

detect_project() {
  case "$PWD" in
    */my-webapp*)        echo "my-webapp" ;;
    */data-pipeline*)    echo "data-pipeline" ;;
    */mobile-app*)       echo "mobile-app" ;;
    *)                   echo "" ;;
  esac
}

PROJECT_ID=$(detect_project)

if [[ -n "$PROJECT_ID" ]]; then
  echo "Task list: $PROJECT_ID"
  export CLAUDE_CODE_TASK_LIST_ID="$PROJECT_ID"
else
  echo "No project detected - using session-based tasks"
fi

exec claude "$@"

II. Installation

Once the file is created, it needs to be moved to the right location and made executable. Run the sequence of commands as outlined in your terminal. Step 4 is essential if you are a Windows user and using Powershell or WSL as your terminal.

# 1. Save script to PATH
mkdir -p ~/.local/bin

# 2. Copy the script to this folder
cp /<original path>/claude-project ~/.local/bin/

# 3. Make executable
chmod +x ~/.local/bin/claude-project

# 4. Fix Windows line endings (CRITICAL for WSL users as files created on Windows have CRLF endings that break bash scripts)
sed -i 's/\\r$//' ~/.local/bin/claude-project

# 5. Ensure PATH includes ~/.local/bin
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

# 6. Reload your shell
source ~/.bashrc

III. Usage

This is the most important project. Typically, you’d launch Claude from your project folder using a simple “claude” command, but going forward you need to use the command: “claude-project”.

# Navigate to project directory
cd ~/projects/my-webapp

# Launch with project-aware tasks
claude-project

# Output: "Task list: my-webapp"
# Tasks now persist to ~/.claude/tasks/my-webapp/

And you’re set! As you work with Claude Code using the workflow outlined earlier, Claude will generate the task list and this will persist across sessions. Here’s and example of a task list I created in a previous session that persisted into the new session and stayed until I exited out of it (note how it shows task #7 as blocked by preceding tasks). This task list will still be available to me in the next session, as long as I start Claude using my aliased command, “claude-project” instead of simply “claude”.

What’s Next?

Claude Code’s task management system is a major step forward, but it’s still in its infancy and I’d love for Anthropic to invest more into this awesome feature. Few enhancements that would help immensely:

Per-project scoping out of the box

Users shouldn’t need a launcher script to prevent task list collisions, and there should be an easier way to set per-project scoping. Claude Code already knows the present working directory; it should default to project-scoped task lists or provide users to manage these lists.

A Task List management layer

Currently, you can’t switch between task lists, archive completed ones, or even see what task lists exist without inspecting ~/.claude/tasks/ directly. A simple “/tasks list” and “/tasks switch” would go a long way.

While there is a /tasks command, I found that it doesn’t work reliably. Here’s a screenshot of the command telling me that there are no tasks currently running, which indicates that this command is meant to manage background tasks such as tool uses, agents and not the task list itself (the task list in the screenshot is always visible, unless I press ctrl+t to hide).

Dependency visualization

The “blocked by” relationships are powerful, but without a way to see the full dependency graph, you’re flying blind on complex projects. Even a text-based tree view would help.

Export/import for team workflows

If task lists persist across sessions, they should be shareable. A JSON export that integrates with Linear, JIRA, or even GitHub Issues would close the loop between Claude’s execution tracking and organizational project management.

These are solvable problems and I hope Anthropic has at least some of these on their, er, “task list” (meta reference, here). Until then, the launcher script approach should help you keep plodding on.

If you found this guide helpful, let me know!

Parallel Paths: Finding Validation for My Context Engineering Framework

Sun, 14 Dec 2025 15:08:51 GMT

Back in September 2025, I realized the hard way that the traditional way of using Prompt Engineering for agentic tasks, while suitable for early frontier models, was not going to be suitable or scalable for complex tasks. But as time has gone by, LLMs have only gotten smarter and AI agents are now capable of stringing towards multi-step tasks, involving multiple tool calls in a single operation. While context windows have also expanded, a larger context window does not really provide a lot of advantages, and in fact provide diminishing returns. Gemini has a 1M token context window, but anyone who has worked significantly with Gemini would tell you how badly Gemini hallucinates as the conversation progresses. In my personal, anecdotal experience, the optimal sweet spot for maintaining effective context is up to 500K tokens, after which the quality degrades. Anthropic’s 200K limit already puts one on a budget, and Gemini’s 1M limit causes a different problem altogether. So, on the one hand you have modern LLMs getting smarter and on the other hand you still have the problem of making the LLM reference the right context. The solution to leverage advantages of modern LLMs is not in effective prompt engineering, but in layering & engineering context effectively.

I spent all of October brainstorming and conceptualizing a context layering & engineering framework that could potentially be leveraged for long-horizon agentic coding tasks. I published my findings and concept early November. You can read it here: https://ashaykubal.com/blog/from-context-chaos-to-clear-an-origin-story/

Feeling Vindicated

Since Thanksgiving rolled around, I’ve been deep into implementation of this framework and getting closer to completing development of the framework’s core engine. In between doing that and keeping up with industry trends, I was pleasantly surprised and felt extremely vindicated to see that lately, the industry discourse also has been shifting towards solving context engineering for long-running agentic tasks.

Research Paper from China & Hong Kong (Nov 23, 2025): Dual-agent memory architecture that outperforms long-context LLMs
- Actual Research Paper: General Agentic Memory via Deep Research
Anthropic’s Engineering Blog (Nov 26, 2025): Effective harnesses for long-running agents
Google Developers Blog (Dec 6, 2025): Architecting efficient multi-agent frameworks for production
LangChain’s Blog (Dec 9, 2025): Agent Engineering – A New Discipline

This work has been a successor to previous research on fundamentals of context engineering. Several publications have expounded the benefits & strategies of effective context engineering, but to particularly call out a couple that I really loved, read these:

LangChain’s blog on Context Engineering (Jul 2, 2025)
Anthropic’s blog on Effective Context Engineering (Sep 29, 2025)

What is interesting is how multiple research teams have coalesced into more or less a shared understanding on how to approach effective context engineering for long-running agents. Three concepts stand out from these publications.

I. Effective Agent/Context Engineering is akin to traditional Software Engineering

LangChain specifically calls it Agent Engineering and distinguishes it from Context Engineering.

As per LangChain: Agent engineering is the iterative process of refining non-deterministic LLM systems into reliable production experiences. It is a cyclical process: build, test, ship, observe, refine, repeat. We see agent engineering as a new discipline that combines 3 skillsets working together:

Product Thinking defines the scope and shapes agent behavior
Engineering builds the infrastructure that makes agent production-ready
Data Science measures and improves agent performance over time

II. A dual-agent harness is the optimal way to layer and engineer effective context

Anthropic developed a two-fold solution to manage context across sessions.

As per Anthropic: The core challenge of long-running agents is that they must work in discrete sessions, and each new session begins with no memory of what came before. We developed a two-fold solution to enable the Claude Agent SDK to work effectively across many context windows:

An initializer agent that sets up the environment on the first run (includes plans broken down into features & deliverables)
A coding agent that is tasked with making incremental progress in every session, while leaving clear artifacts for the next session This research demonstrates one possible set of solutions in a long-running agent harness to enable the model to make incremental progress across many context windows. However, it’s still unclear whether a single, general-purpose coding agent performs best across contexts, or if better performance can be achieved through a multi-agent architecture. It seems reasonable that specialized agents like a testing agent, a quality assurance agent, or a code cleanup agent, could do an even better job at sub-tasks across the software development lifecycle

III. Required & Necessary Context is a compiled view of a rich stateful system

Google considers that to build production-grade agents that are reliable, efficient & debuggable, context engineering is required. Google also defines context engineering as a “first-class system with its own architecture, lifecycle, and constraints.

As per Google: In previous generations of agent frameworks context was treated like a mutable string buffer. But now Context is a compiled view over a richer stateful system. In that view:

Sessions, memory, and artifacts (files) are the sources, i.e. full structured state of the interaction & its data
Flows and processors are the compiler pipeline, i.e. a sequence of passes that transform that state
The working context is the compiled view you ship to the LLM for this one invocation

Realizing These Insights Personally

The reasons these three concepts stood out particularly to me is because I realized these myself organically over the last month while actually implementing the CLEAR framework.

As part of the implementation, I’ve been managing session states & transitions, knowledge (requirements & past decisions), and project plans in a semi-automated manner. While doing that, I also set up a metrics capture mechanism & dashboard that would allow me to measure and quantify the efficacy of my semi-automated system. I plan on using this as a baseline to measure the efficacy of the CLEAR framework once it is implement by doing a comparative analysis between projects built with and without CLEAR.

Here’s what the numbers say:

And here’s what they mean:

On an average each session lasted for ~2.5-3 active, actual hours
I consistently hit close to 70% or more token usage consumption (out of Claude’s 200K token window) every session, which was the threshold I had set to trigger session handoff and transition to a new session
However, the output of each session differed from each other. In some sessions, I was able to get Claude to write over ~1500 lines of code, while in some sessions that number was close to ~700.

This led me to further analyze the session data and classify my sessions into session types & per session productivity by session type. This revealed some startling insights:

Validation

The session metrics with my semi-automated context management in place prove the need of every single one of the three main tenets I outlined above, further validated by research that Anthropic, Google & LangChain have published in particular.

While the V1.0 of the CLEAR framework does not immediately address the three tenets in full, it aims to address each of these partially at the very least.

The framework initialization protocol immediately stresses the creation of a detailed plan, followed by breaking down the plan into features – these serve as the foundational base that the build is executed against
The inclusion of specialized sub-agents running scoped tasks and the main orchestrator agent recording artifacts like technical & architectural decisions, session progress and handoffs address the dual-agent harness
The ability to self-manager and regulate sessions & session progress with auto-loading of minimal viable context using progressive disclosure principles is akin to loading a compiled view into memory at the start of a new session providing the agent with the minimum information required to complete the scoped tasks

That being said, reading and processing these publications has also provided me a vision of what the V2.0 improvements to the framework, and I am excited to continue building out this framework.

From Context Chaos to “CLEAR” – An Origin Story

Mon, 10 Nov 2025 03:43:50 GMT

The No-Code Journeyman

I started AI-assisted prototyping with no-code tools like Lovable, Bolt, and Figma Make, but hit frustrating limitations: platform lock-in, no code downloads, and hidden implementation details. Debugging was painful without transparency into changes, and I couldn’t prevent or understand questionable AI decisions. For cost efficiency, these tools also use “smart routing” to assign requests to different AI models without transparency, but this meant I’d get stuck on simple problems when routed to weaker models. Eventually, I abandoned these platforms.

I switched to VSCode with Claude Code, finding CLI assistants liberating for rapid prototyping. However, I quickly identified the core challenge: managing memory, context, and tokens. CLI coding assistants start each session with no memory or context of previous work. To address this, I set up a method of elaborate documentation for Claude Code with 3 memory layers:

Long Term Memory – The project spec and complete blueprint with everything Claude Code needed to build. This lived in CLAUDE.md which Claude would load at the start of every session
Working Memory – Summaries of previous sessions, key technical decisions, what got done and what’s up next. This was all in one doc called claude-summary.md
Episodic Memory – Records of specific visual changes and code states so I could roll back if things went sideways. This was version snapshots plus another summary called visual-changes.md

Spiraling from Organization to Chaos

I tested this setup by building my personal website. My build sessions started strong, but I soon realized I’d only solved memory and not context management or token waste. Claude knew where we left off, but loading all that context consumed tokens upfront. As summaries and episodic files grew, I accomplished less per session before hitting limits and context rot. I only deployed successfully by keeping scope extremely tight between sessions.One thing became abundantly clear: I needed a new approach to manage Memory, Context, AND Tokens simultaneously.

I was reminded of the Chinese proverb:

“If you ignore the dragon, it will eat you. If you try to confront the dragon, it will overpower you. But if you ride the dragon, you will take advantage of its might and power”

To make Claude Code work for me, I had to ride the dragon. That meant going into research mode and find out how. I decided to do what I do best: approach this as a product manager and identify the main problem areas that I needed to solve. I analyzed my build process: reviewing token consumption, productive time per session, and episodic memory files.

The token consumption math was brutal, and better expressed by this visual.

To put things into perspective: It took 46 sessions to deploy the site, with severe struggles near the end.

A Shared Pain

Token consumption analysis confirmed my suspicions, but analyzing session summary data files revealed deeper issues. Beyond memory, context, and token management, I also needed to solve: implementation inconsistency, decision persistence, proactive monitoring, and standardized handoffs.

But then I was like: Hold on, I’m but a fledgling in this arena. Surely I’m not the only person to identify these problems. What are the others doing? A few nights of doom-scrolling Reddit communities like r/ClaudeCode confirmed I wasn’t alone. Builders faced identical challenges:

“Anyone else losing their mind with token limits?”
“How are you guys managing your sessions? I’m getting rate limited in 15 minutes, this is beyond unusable”
“I’m so done with this. I’m seeing three different implementations for similar APIs in three different sessions. I don’t know who thinks AI can replace humans”
“I spend more time bringing Claude up to speed at the start of every session than actual coding. By the time he’s ready to start coding, my conversation gets auto-compacted”

I found that unlike me, seasoned developers were already aware of these issues. Some used elaborate documentation methods that hit the same limits I did. Others kept detailed session notes that created historical records but couldn’t intelligently surface relevant information. Some tried summarizing previous sessions to save tokens, but lost critical implementation details. Others built external memory tools that helped with memory and context but lacked automated entry/exit points and didn’t formalize patterns, leaving inconsistent implementations unaddressed.

I also explored promising frameworks like claude-mem & BMAD-Method but they solved specific problems without addressing all the issues together.

Brainstorming

The AI-assisted coding community (developers & product designers) clearly faced significant, persistent problems that needed addressing. As a product manager who’d experienced these issues firsthand, I understood the problem space deeply. I saw that existing solutions tackled issues in isolation rather than holistically, and understood why. Engineers often focus on specific problems with low-effort solutions, missing the bigger picture. Product Managers often envision solutions without considering technical feasibility. With my product management and engineering background, I was uniquely positioned to conceptualize a framework that solved these issues holistically while remaining technically feasible, extendable, and accessible to both developers and product designers. Even if I didn’t succeed in coming up with something, I felt I needed to at least try.

I researched solutions systematically, using Claude Opus as a brainstorming partner, ironically using Claude to design a memory system for Claude Code.

Phase I: Solidifying the Layers

The most crucial insight that I gleaned in the first phase of my research was understanding in broad swathes the main pillars that could manage memory & context effectively.

Persistent Knowledge: Critical information (technical decisions, architecture, requirements) that was sacrosanct and must persist indefinitely. This would be the foundational layer
Reusable patterns: Standards (coding conventions, implementation approaches, quality gates) applied consistently across similar tasks. This would be the consistency layer
Focused Execution: Work with clear boundaries and minimal context to prevent scope creep and token waste, This meant well-defined criteria, dependencies, standards, knowledge references, automated context monitoring and session handoff protocols. This would be the execution layer

Implementing just one or two of these systems would create an incomplete solution. They needed to work together as an integrated whole.

Phase II: Exploring the Layers

With the three-layer concept, I explored each layer’s contents and interactions through brainstorming sessions with Claude. This yielded an initial architecture: four interconnected pillars powering the system.

Knowledge Bases for persistent project memory. Every decision, architectural choice, and business rule documented with rationale. Future sessions load only relevant knowledge.
Workpackages for focused units of work with clear scope, explicit dependencies, and specific context requirements, solving token exhaustion by loading only what’s needed.
Tools to encode reusable patterns. Instead of hoping for consistency, tools explicitly define “how we do X in this project.” Modular, reusable, and shareable.
Agents as focused experts for specific tasks rather than a generalist trying to remember everything.

I then pondered over the inter-connectedness of this system and their overall impact on context management debating some key questions & solutions to them.

What separates knowledge bases from tools? How do we scope workpackages? Are layers hierarchical or networked? Do knowledge bases need categories? How do we prevent information bloat? How do we ensure only minimal required information is loaded per task?

This process helped further define each layer more clearly and establish their relationships.

Knowledge Bases are structured repositories with templates for different knowledge types. Each captures decisions, rationale, alternatives considered, and tradeoffs accepted.
Workpackages are complete specifications with dependencies, context requirements, success criteria, and agent assignments, representing unique units of deliverable functionalities.
Tools are executable patterns with metadata, examples, and integration points. They’re modular – add or remove without breaking the system. They are used by agents and referenced in workpackages
Agents are invoked via workpackage specs or intelligently based on tasks. They can use tools, which can reference sub-agents to achieve objectives.

Phase III: Integration & Workflow

With the relationships between the four cogs fully defined and a deep idea of how these cogs would work together, I dove into further detailing out the core characteristics of this framework.

This resulted in the formulation of the key design decisions & principles that would form the bedrock of this this framework.

Session Management: Each AI-assisted code sessions would need intelligent monitoring. The framework should track token usage and trigger handoff protocols before limits are hit. This would require some some custom monitoring code that could hook into Claude’s progress systeam & monitor it passively in the background, triggering appropriate documentation and session handoff protocols once token consumption crossed a certain threshold.
Progressive Context Loading: Not every session would need full context. The framework should load context progressively: start with minimal essential information, add workpackage-specific context, then layer in relevant knowledge bases and tool calls automatically during development as needed.
Automatic Documentation: Developers shouldn’t need to manually update knowledge bases. The framework should detect when decisions are being made and prompt for documentation at natural points.
Cross-Session Continuity: Each session should know where the previous session ended and what the logical next steps are. This requires coordination between session management, workpackage tracking, and overall project plan management.

Phase IV: User Segmentation & Understanding Claude

With the framework conceptualized, I needed to identify my target user segments. With a plethora of AI-assisted coding platforms, all with users facing similar problems, I decided to focus on one segment first before expanding. I would have also preferred implementing a platform-agnostic framework, but I had limited resources as the single person working on this in my free time. I didn’t know if this framework was even implementable, let alone adoptable, and lacked time and resources for extensive user research & outreach across platforms. Most importantly, I was building this for myself to enable other personal projects. Given my travails with Claude Code, focusing on Claude Code users as the target user segment & platform became the natural choice.

After using Claude Code with a “learn as you use” approach, I realized I needed deeper platform knowledge to implement the framework. I found that the problems I was trying to solve were ones Anthropic had already recognized. This excellent blog post by Anthropic on effective context engineering practices served as affirmation for what I was trying to do.

I was quite excited to discover that for effective context engineering, Anthropic had equipped Claude with capabilities that aligned perfectly with the framework’s needs and could be leveraged to manage organization, memory and context.

Hooks: User-defined shell commands that execute at various points in Claude Code’s lifecycle. Hooks provide deterministic control over Claude Code’s behavior, ensuring certain actions always happen rather than relying on the LLM to choose to run them. Hooks allow even-driven automation.
Skills: Organized folders of instructions, scripts and resources that can be loaded dynamically to perform specific tasks that are repeatable and predictable. Skills operate on the core design principle of Progressive Disclosure, making them flexible & scalable, letting Claude information load information only as needed.
Custom Sub-agents: Specialized AI personalities that Claude Code can invoke to handle specific type of tasks. Each sub-agent has a specific purpose & expertise, uses its own context window separate from the main conversation, can be configured with specific tools, and includes a custom system prompt that guides its behavior.
Plugins: Allow extension of Claude Code’s functionality by adding custom commands, cubstom sub-agents, skills and hooks.
Token counting & monitoring: Determines token count in messages and monitors usage.
Native Session monitoring: Persistent session identifiers for git attribution and session management.

Phase V: Crystallizing the framework

I then set about formalizing how my framework would leverage Claude Code’s native capabilities.

Claude Code Hooks: Event-Driven Intelligence

Hooks would serve as the event-driven intelligence at the heart of the framework that would perform automated session management, knowledge base updates and workpackage status updates.

Native Session IDs: Traceability Without Overhead

Session IDs would enable Git commit attribution and organize session logs, creating a traceable history. Knowledge bases and workpackages would reference session IDs to track decisions and completions, while also enabling easy work resumption.

Skills: Progressive Disclosure for effective context management

Claude’s game changing skills feature with progressive disclosure would be extensively leveraged for repeatable tasks and to power sub-agents. A typical skills file load would look something like this:

YAML frontmatter – contains metadata, hook definitions and configuration. Always loaded
Core instructions & patterns in Markdown – always loaded
Examples library – contains extensive examples for effective leverage. Loaded only on demand when utilizing the skill
Reference documentation – contains detailed explanations and edge cases. Loaded only when needed
Scripts and tools – contains actual executable loaded. Loaded only when code execution or writing would be required.

Sub-Agents: Native specialization with independent context

Anthropic’s sub-agent system would provide native support for building & calling specialized agents that would work in their own context window, leveraging skills and pulling reference documentation and resources as defined in each workpackage.

Knowledge Bases, Session Summaries & Workpackages: The persistent memory

Auto-maintained knowledge bases, session summaries, and workpackages would serve as long-term and episodic memory. Skills or sub-agents would load specific sections just-in-time with minimal context.

Plugin Architecture: Seamless Integration

Finally, the framework would be distributed as a Claude Code plugin on the Claude marketplace instead of being offered as an external CLI tool, leveraging Anthropic’s native support. This would also enable native distribution & seamless updates to users.

Phase VI: Naming & Identity

The final phase was naming the framework. After brainstorming with Claude, I settled on CLEAR (Context Layered Engineering for Agentic Resources), capturing the clarity when chaos becomes manageable.

But there was something deeper. In Claude Code and terminals, the /clear command means one thing: wipe everything. Clear the screen, memory, and context. It represents erasure and starting over with nothing.

The CLEAR Framework inverts that meaning entirely. Instead of /clear meaning “memory gone,” CLEAR would now mean:

Clarity of memory – decisions preserved and accessible
Contextual clarity – relevant information surfaced automatically
Clear continuity – seamless flow between sessions

Conclusion

And that is the origin story of CLEAR, a framework conceptualized for working efficiently with Claude Code. Putting it all together, this is how the CLEAR framework would be powered by Claude Code’s native capabilities.

The core of the CLEAR framework

result in the framework meeting its design principles.

Now that the framework is conceptualized and formalized, I’m excited to move forward with implementation! I’ll be switching over to my trusted Claude Sonnet 4.5 and VSCode to bring this to life. I won’t be just building it, I’m going to use it right away for a sample project and then for all my future personal projects. You know, like the term Microsoft’s Paul Maritz made famous back in 1988: “Eating our own Dogfood“

If things go well with the framework, I’m looking forward to adding some cool enhancements down the line: things like graph search capabilities to track and find those informal decisions we make along the way, plus a bunch of other specialized sub-agents beyond the core ones.

I’d really love to hear what you think about this framework! Feel free to share any thoughts, feedback, or even criticisms you might have; I’m all ears!

AI-Assisted Rapid Prototyping – Part IV

Sun, 05 Oct 2025 14:45:56 GMT

In Part IV of this AI-assisted Rapid Prototyping series, I’ll focus on the fourth step: Realize & Crystallize. As a reminder, my prototyping process has five stages, outlined below.

The Realize and Crystallize stages are inseparable; this is where you actually build & iterate on the prototype. Start by creating an initial prototype, a “stage zero” that’s functional and includes all the basic features you envisioned for your MVP. Then iterate by gathering user feedback, keeping what works and discarding what doesn’t. Once you’ve built out your MVP target, you’re ready to either deploy to production or hand over the prototype to the engineering team, depending on whether you’re prototyping or building the final product yourself.

Fire Your Engines!

In the previous articles, I showcased how I set up a.) an Initial Master Prompt (IMP), b.) a full project plan with product requirements, and c.) a memory management & snapshot strategy, to guard Claude Code and Gemini CLI from context rot and ensure that I could rollback to a working version in the event of a catastrophic failure.

With all the initial documentation files in place, I then created a new folder for my personal website project and added all the documents in there.

Next, I launched the WSL (Ubuntu) terminal in VSCode and fired up the CLI coding assistants. I initially started with Gemini CLI to build the project scaffolding. Project Scaffolding refers to the use of pre-built structures or templates to accelerate the initial setup and foundation of a new project, similar to how physical scaffolding supports construction workers.

I then copy pasted the initial master prompt into the console and hit enter. The documentation that I had set up already provided Gemini with the exact scaffolding to set up, which looked something like this:

Once the scaffolding was set up, I switched to Claude to get started with the application development.

After providing the initial master prompt to Claude, Claude asked me for confirmation to begin and once that was done, it generated hundreds of lines of codes within minutes, finally generating a landing page, with placeholder content which it hosted on a local development server for me to view.

This moment justified all the effort I put into the previous steps. Everything I did in the initial setup, Visualize, and Strategize phases paid off. The V1.0 of my prototype matched almost exactly how I envisioned the final product. This isn’t to say everything was perfect, but watching Claude spin up a functional website, complete with all pages and working navigation, from a single initial master prompt validated my decision to create thorough documentation and set up the necessary controls before having the model write a single line of code.

Iterate & Polish

At this stage, my rapid prototyping process was technically complete. I had a responsive, clickable, functional prototype with placeholder content that worked on both web and mobile. For a commercial or enterprise app prototype, this is where I’d solicit user feedback and run user acceptance testing to identify issues with user flows and feature requests. But since this was my personal website, my user base consisted of my wife and me with the grudging, approving nods from my cats serving as senior stakeholder sign-off. Through several rounds of testing, I fixed several issues and implemented a couple of entirely new features. With each session, my prototype became more polished and started resembling a high-fidelity prototype.

The iteration and polish stages weren’t without issues. I went through 19 sessions, each lasting a few hours, before I had a website ready for primetime. My documentation also tracked the hours spent on iteration.

Session Management

As you can see in the image above, the prototyping effort spanned multiple sessions. Let’s first understand what a session means and why it matters. Every time you type “claude” or “gemini” into your terminal, you start a new session. Unlike the popular mobile apps for ChatGPT, Claude, or Gemini, the command line coding agent starts with no memory at all. This means you must provide the initial master prompt every time, which directs the agent to review the instructions. In my case, the IMP directed the agent to review all project specs (long-term memory), the summary from the previous session detailing what was accomplished and next steps (short-term memory), and the specific visual changes made in the last session (episodic memory).

There are advanced memory management techniques that provide coding agents with memory retrieval tools; I’ll explore these in another series. But for building a personal website, I didn’t bother with all that. Instead, I relied on my documentation system to provide context at the start of each session. This was a double-edged sword. Right after the initial prompt, I loaded the agent’s contextual memory, which progressively reduced the remaining context available for new work before context rot set in. I tackled this by keeping each session small and focused on 4–5 immediate tasks. At the end of each session, I asked the agent to update all documentation, take a version snapshot (a backup of all code and resources), and document the immediate priority tasks for the next session.

This ensured that once I started a new session, the agent immediately knew what it had to achieve using the notes it had generated in the previous session.

Think about it like Leonard Shelby leaving himself elaborate notes, photographs and tattoos in Memento to account for his amnesia.

A Word of Caution

After the initial prototype was generated, I ran extensive testing and uncovered numerous functional and cosmetic defects. I had Claude fix issues related to alignment, color schemes, and text and image rendering. Some of the more serious functional issues I found and fixed were:

Image galleries in published posts did not render
Embedded content, especially PDFs or slide decks, did not render
HTML characters were not being stripped or rendered correctly
Featured images on posts were broken
The search and filter functionalities on the Blog and Portfolio listing page were broken and did not render correctly
The skills cloud sat at the bottom of the screen and looked terrible – I completely redid it as a rolling ticker running across the middle of the page

I’m pointing these out to make something very clear:

While coding agents do a good job of generating code, you are still in the driver’s seat. The depth of your validation ultimately determines the quality of the output. Like they say, “It’s not the car, it’s the driver.”

In one instance, Claude was about to make a change and I stopped it. I asked it to first analyze and confirm that the change wouldn’t impact the same feature on mobile. It did, and found that the change would’ve broken a perfectly working mobile feature. It then set up a separate configuration so that changes to one didn’t impact the other.

💡Pro Tip: While using command line coding agents, you’ll be asked to confirm if you want the agent to update code files. One of the options is to always allow the change next time. DO NOT select this option. You may not understand the code, but while the agent is making changes, you can logically infer what is being changed. In many cases, you can stop the agent from making the change and ask it to analyze something more holistically first. I’ve found this to be a very effective method for reducing regressions due to changes.

Unexpected Issues

Like any work project, you’ll encounter unexpected issues no matter how well you plan. Be ready to pivot when they arise.

Once my prototype was ready, I decided to populate it with real content. During the planning phase I had worked out with Claude that I’d be using WordPress as a headless CMS to publish content which would then come up on my website. But when the time came to integrate, I found that Claude had assumed I was using wordpress.org and not a free plan on wordpress.com. These were two completely different things and the entire code base up until that point in time was built assuming that I’d be using wordpress.org. I then had to pivot, with Claude having to rewrite significant portions of the code, including setting up an API based connection and parser to pull content from wordpress.com and then display it on the site.

Learning & Discovery

Every project you undertake will reveal that each Realize & Crystallize phase offers an opportunity to learn something new.

Building a personal website may seem like one of the simplest initiatives you can take on. But while building this prototype, I learned how integrations with headless CMS work, how to set up a site for SEO optimization, and how to configure analytics. This is invaluable knowledge I’ll carry into my next project.

Deployment & Next Steps

Normally, once the prototype is complete, the next stage, i.e. Productionize, begins. This is where you hand over your functional prototype to the engineering team. You can also use the design to generate user stories in JIRA using MCP server-based integrations. I’ve already experimented with integrating Figma with JIRA to automate this process. Setting up a custom MCP shouldn’t be too difficult.

For my personal website, I decided to push the envelope and turn the prototype into a live site. I worked through the site once more from an end-user’s perspective, adding finishing touches and visual polish until I had a deployment-ready website.

Despite what you may read, I wouldn’t recommend relying solely on coding agents for enterprise projects or live sites with paying users. Coding agents excel at prototyping and building a basic codebase.

The end product of realizing the vision & crystallizing it is shown below. In the next and final part in this series, I’ll cover deployment, i.e. actually taking this prototype and turning it into a live site (again, not something I’d recommend for enterprise initiatives).

Hit the comments if you’d like to discuss more.

AI-Assisted Rapid Prototyping – Part III

Sun, 05 Oct 2025 14:37:54 GMT

Welcome to Part III of this series in which I will focus on the Strategize phase of rapid application prototyping. If you haven’t already, you can

Read Part I here: Prototyping using Gemini & Claude – Part I
Read Part II here: Prototyping using Gemini & Claude – Part II

Step 2: Strategize

The Strategize phase focuses on developing the master prompt for Claude and Gemini, our chosen assistants. Within this initial prompt, you must ensure the product brief created in the Visualize phase remains available to the assistants as a constant reference. Creating the master prompt is just the beginning. After providing it and initiating the build, you’ll engage in extensive conversations with each coding assistant – often switching between them – to achieve your precise objectives.

Remember that unlike traditional UX design, AI-driven rapid prototyping generates actual code, not just mockups. Despite thorough preparation and reference materials, AI will make mistakes. These errors manifest as code defects that can seriously impact your prototype’s functionality. Learning to anticipate these issues and developing quick response strategies is crucial for saving time and reducing frustration. I learned these vital lessons through difficult experience.

You should also prepare for Context Dilution. As conversations with coding assistants lengthen, you will hit the context window limits of your chosen LLM. The assistants will begin losing track of earlier exchanges, often suggesting previously attempted changes that you know are ineffective. This becomes extremely frustrating, making it essential to develop strategies to anticipate and mitigate Context Dilution.

Finally, once your functional prototype is ready, you’ll make numerous visual adjustments to align the app with your vision. Each change risks breaking something. Having a reliable recovery mechanism is therefore essential.

Anecdote: One of application prototypes was coming around perfectly until I decided to add some minor finishing touches like SEO optimization and code cleanup. The Claude Code agent confirmed it had completed all tasks, but when I tested the application one final time, I discovered the landing page was completely broken. All my meticulous changes had vanished. The interface looked like the V1 that Claude had created after my initial prompt, and navigation between pages no longer worked. With growing dread, I checked the other pages and found everything was broken throughout the application. I asked Claude Code to revert to the previous working version, but despite confirming it had done so, nothing changed. I spent a frantic 3 hours (not counting the 5-hour break when Anthropic locked me out for exceeding my plan’s rate limits) trying to identify all the issues and get Claude to fix them. Nothing worked. As a last resort, I asked Claude to reference my original PRD and rebuild the application to that specification. This reverted my application to its most basic version, but at least the core functionality worked again.

Documentation & Memory Management Strategy

To avoid disasters like these, it is important to have a documentation & memory management strategy. For every application prototype that I work on, I make a point to ponder on and answer these questions within my master prompt. These directions enable me to ensure that a.) I am always in a position to recover from a disaster, and b.) my coding assistants do not lose context.

Stage 1: Answering the basics

What does my versioning strategy look like?
- Is this application complex enough to create a git repository and check code in frequently?
- Is the application complex enough for me to maintain dev and main branches, followed by periodic merging?
- Is the application simple enough to maintain a changelog file to document every change, so that exact code revisions are preserved and roll backs continue to be viable options?
Do I need forking? I typically consider this as an option if I plan to prepare multiple iterations for A/B testing. Forking allows for creating multiple offshoots of the same basic applications, but for this to work you also need to check code in to GitHub or another source control hub.
What is my check-in frequency?
What is my code refactoring strategy and frequency?
What is my deployment strategy?

Stage 2: Managing visual changes & assistants

How do I manage visual changes? As you start visually polishing the application, you will need to make a number of small and big changes to the UI and the UX, and you absolutely need to retain the ability to go back and revert changes if they don’t work.
How do I manage context switching between AI assistants & context dilution?

After answering these questions, you’ll have a clear vision for your master prompt. A significant portion of this prompt establishes the foundation for your project through a documentation strategy, giving the model a reference path to stay aligned with your goals. Consider your documentation strategy as providing the AI with three distinct memory layers:

Long Term Memory (Project Specification Document) – This document, generated by your master prompt, contains the unchanging complete blueprint. Claude Code explicitly requires this document, and while Gemini doesn’t mandate it, maintaining this document for Gemini is equally essential. Each file should be tailored for its intended assistant. For instance, if you’re using Claude Code for functional development and Gemini for visual enhancements, specify these roles in the respective files. These files are typically named Claude.md and Gemini.md and should use markdown format.
Working Memory (Summary Files) – Named as claude-summary.md and gemini-summary.md, the files track what has been accomplished and what is currently in focus. Think of these files as the AI’s working notebook. They capture not just what was done, but what’s currently in focus, what decisions were made, and what comes next. These files directly address the context dilution problem.
Episodic Memory (Visual Changes File) – The visualchanges.md file functions as episodic memory, documenting specific visual change moments and enabling you to revisit previous visual states. Each entry in this specialized UI changelog captures not only what changed but also includes the “before” state and precise rollback instructions. If you decide yesterday’s new card design isn’t working as expected, you can simply find the entry and follow the exact reversion steps. This file serves as a time machine for your website’s appearance, independent of your code versioning system.

This three-layer approach resolves two critical AI-assisted development challenges. First, it addresses context dilution. As conversations lengthen, the AI’s sliding attention window causes earlier details to fade from immediate awareness. Your summary files serve as concentrated extracts of recent relevant work, ensuring the AI maintains situational awareness. Second, it manages visual changes, which are subjective and sometimes don’t work as initially expected. The visual changes file creates an independent visual “undo” system that complements your code versioning. Finally, the unchanging project documentation serves as the authoritative product specification that coding assistants must reference before, during, and after completing each milestone.

Handoff Protocol

Your master prompt should also document a handoff protocol that ensures smooth transitions between Claude and Gemini. This means that in your master prompt, you should add instructions that before switching assistants, the current AI updates its summary file with exactly where things stand, what it was working on and what should happen next. This is like leaving detailed notes for a colleague taking over your shift, the incoming AI assistant knows exactly where to pick up the work.

Include a handoff protocol in your master prompt to ensure seamless transitions between Claude and Gemini. Direct the current AI to update its summary file before switching assistants, clearly documenting the current status, work in progress, and next steps. This is like leaving detailed notes for a colleague taking over your shift, the incoming AI assistant knows exactly where to pick up the work.

Update Frequency, Baselines & Structure

Your master prompt should specify clear document update intervals to prevent documentation drift. Include requirements that summary files must be updated at natural breakpoints—such as the end of a session, before switching assistants, or when reaching milestones. For the visual changes file, insist that updates be documented before implementation rather than after. This prevents the common problem of forgetting what the original state looked like.

Also have the master prompt include the concept of a “baseline visual state.” This documents the initial visual state when you first set up the design system with your specified color palette. Direct the AI to document this starting point in the visualchanges.md file. This baseline provides a reliable ground truth you can always return to if needed.

Finally, instruct the master prompt to maintain documentation in a structured format. I typically store these five files in a dedicated ‘docs’ folder at the root of my project. This organization separates documentation from code while keeping everything easily accessible. Include the baseline visual state in the visual changes file as both a template and example entry, guiding the AI on proper formatting for future entries. If your project includes wireframes, store these in a folder within the same docs folder. Also include a manifest file documenting what each file represents.

Generating the master prompt

After all this preparation, we finally arrive at the critical step: creating an initial master prompt for your coding assistant. For this, I use Meta Prompting, a technique where you use an LLM to generate and refine your master prompt. OpenAI offers an excellent article on Meta Prompting that explains this approach.

I typically divide this process into two straightforward steps:

First, generate a prompt to create comprehensive project documentation, then use that prompt to produce the documentation
Second, use the completed project documentation to create an initial master prompt for your coding assistants

My workflow looks something like:

For project documentation and master prompt generation, I rely on models with superior reasoning capabilities. Claude’s Opus 4.1 with extended thinking and “Explanatory” style consistently delivers the best results. During my research into effective prompting methods, I discovered the “Ultimate Prompt Architect” (UPA) on GitHub—an exceptional resource that I’ve configured as a Claude project to generate high-quality master prompts.

Step 1: Generate a prompt to create project documentation

After setting up the prompt generator as a Claude project, I provided it with the product brief along with all design system elements, color palette, and other details I had documented during the Visualize phase and document strategy steps.

Here’s what my comprehensive 24-page master prompt for generating project documentation looked like:

Master Prompt

I then initiated a new conversation with Claude Opus 4.1 and submitted this master prompt to generate the complete project documentation.

Step 2: Use project documentation to generate an initial master prompt

After generating all the project artifacts, I returned to my Ultimate Prompt Architect to create the initial master prompts for Claude Code and Gemini CLI.

Since I planned to switch between these two assistants during development, I specifically asked the UPA to address context switching in the master prompts.

The UPA then delivered the following initial master prompts:

Gemini CLI Master Prompt

You are Gemini CLI, responsible for the initial setup and configuration phases of a personal website project.

## Your Primary Responsibility: Phases 1-2
You are specifically tasked with completing the foundational work:
- Phase 1: Project Initialization (Tasks 1.1 through 1.4)
- Phase 2: Configuration Files (Tasks 2.1 through 2.3)

## Documentation System
Your key documents:
1. **gemini.md** - Contains your detailed task checklists
2. **gemini-summary.md** - Track your progress here
3. **visualchanges.md** - Document any visual decisions
4. **wireframe-manifest.md** - Note if you reference wireframes

## Starting Protocol
1. Read gemini.md focusing on Phases 1-2
2. Check gemini-summary.md for current status
3. Execute tasks sequentially using the exact commands provided
4. Check off completed items as you go

## Handoff Preparation
When you complete Phase 2, prepare for handoff to Claude by:
1. Updating gemini-summary.md with "Phase 1-2 Complete, ready for Claude Phase 3"
2. Documenting all created files and configurations
3. Noting any decisions that will affect component implementation
4. Creating a version snapshot
5. Clearly marking Phase 3 as "Ready to Start"

Your goal: Create a rock-solid foundation that Claude can build upon for the design system and component work.

Ready to begin with Task 1.1?

Claude Code Master Prompt

You are Claude Code, responsible for the design implementation and component architecture phases of a personal website project.

## Project Status Check
First, determine where the project stands:
1. Read claude-summary.md to check current state
2. If Phases 1-2 are complete (by Gemini), proceed to Phase 3
3. If project is not started, you CAN begin from Phase 1 if needed

## Your Primary Responsibility: Phases 3+
After foundation is laid, you excel at:
- Phase 3: Carbon Design System Integration (custom theming)
- Phase 4: Component Development (with wireframe interpretation)
- Phase 5+: Complex integrations and architectural decisions

## Documentation System
Your key documents:
1. **claude.md** - Your architectural guide and philosophy
2. **claude-summary.md** - Your progress tracking
3. **visualchanges.md** - Critical for component visual decisions
4. **wireframe-manifest.md** - Your visual source of truth

## Starting Protocol
IF project is initialized (check for package.json, directory structure):
- Begin with Phase 3: Carbon Design System setup
- Reference wireframes in docs/wireframes/ for visual guidance
- Focus on the "why" behind design decisions

IF project is NOT initialized:
- You can execute Phase 1-2 if needed
- But note that gemini.md has more detailed setup commands

## Your Strengths
Leverage your abilities in:
- Interpreting wireframes and making design decisions
- Understanding component architecture patterns
- Solving complex integration challenges
- Explaining architectural reasoning

Ready to assess the project state and proceed accordingly?

With the completion of the Strategize phase, I was now completely prepared to begin building my personal website. In the next part, we’ll explore the Realize phase and discuss how other phases apply to rapid prototyping.

I welcome your thoughts on this framework and would be happy to address any questions in the comments.

AI-Assisted Rapid Prototyping – Part II

Sun, 05 Oct 2025 14:26:09 GMT

Welcome to Part II of this series in which I will focus on the thought process I use before starting to prototype an application from zero into something tangible. If you haven’t already, you can read Part I here: Prototyping Applications using Gemini CLI & Claude Code Together – Part I.

As outlined in Part I, I have developed a framework that can be applied to any prototype build:

Visualize – Define clearly what you want to build
Strategize – Create a concrete plan for implementation
Realize – Build and test your prototype
Actualize – Deploy, validate, and collect feedback
Crystallize – Keep what works, discard the rest
Productionize – Hand over to Engineering

In this article, we will focus on the first step, i.e. Visualizing your application before starting to build it.

Product Discovery: Since this article focuses on application prototyping which falls within the Design phase, we shall assume that product discovery has been completed. This means you’ve analyzed a market, identified a problem to solve, conducted competitor research, defined target segments and their jobs-to-be-done, and determined application features. Only after completing these essential steps are you ready to begin building application visuals.

If you’re only just getting your feet wet into the world of rapid prototyping for upskilling, Product Discovery can be skipped. But if you’re prototyping for an application that you plan to launch or you are prototyping in an enterprise setting, the Discovery phase is absolutely critical to ensure that you build an app prototype for something that users want and will use.

Step 1: Visualize

During the Visualize stage, I focus on creating a detailed PRD that outlines my priorities and desired appearance, while also defining the fundamental non-design components of the application.

I typically divide product requirement documentation into two stages. In each stage, I task myself with answering a series of targeted questions to clarify and solidify my vision for the application I want to build.

Stage 1: Features, Workflows & Integrations

The questions in this section represent essential considerations for any competent Product Manager, regardless of whether they’re using GenAI for rapid prototyping. However, when specifically leveraging AI for prototyping, documenting all these elements becomes crucial. The resulting documentation serves as the comprehensive blueprint you’ll provide to your chosen model and tool, ensuring that the model understands your complete vision, i.e. immediate needs as well as future plans.

What are the features I need to support at launch, i.e., what is my MVP target?
What features will I add as future enhancements?
What different workflows should my application support at launch?
- What user journeys need to be supported?
- Are there mandatory or regulatory workflows that must be implemented on the frontend? (Example: For a mortgage application prototype, KYC and proof of fund workflows are both mandatory and regulatory)
- Are there conditional workflows to support? (Example: Answering “yes” to a form question reveals additional fields requesting more details)
- Are there IAM (Identity Access Management) controlled workflows? (Example: On a resource management platform, only supervisors can approve paid time off)
What workflows should I add in future phases?
Who are my target user segments, and which segments will I focus on at launch?
What are my different user personas, and what IAM controls need to be in place at launch?
What minimum integrations must I support at launch? (Example: Login flows like Google, Meta, SSO integrations, payment integrations, etc.)
What integrations should I add as future enhancements? (Example: Google Drive for file imports, data export tools, location APIs, etc.)

Tip #1: Leverage AI to identify blind spots and considerations in product requirements. If you’re working independently or working on your hobby project on personal time, AI can also help you comprehensively craft and document these requirements. I will cover this in detail in a future article.

Tip #2: Start with a comprehensive list of everything you want to include in the application, giving you a complete book of work to work from. Then use NNL (Now, Next, Later) to identify your MVP, most-mvp features and future enhancements.

And now, on to the fun stuff…

Stage 2: Look & Feel

This is where you should carefully consider your application’s visual design. While most enterprise settings provide brand guidelines and design systems to follow, if you’re working independently or building a hobby app prototype, it’s crucial to think deeply about each aspect of the look and feel and document your vision precisely. I recommend these two essential resources for anyone serious about building effective application prototypes:

Figma Design Basics: This comprehensive guide covers every fundamental aspect of design and is invaluable for understanding product design. It explains everything from tangible assets like wireframes and mockups to design concepts like lateral thinking, design thinking, human-computer interaction, design complexity, and important design aspects like accessibility, color palettes, color theory, and typography.
Figma Design for beginners course: This course teaches you to approach design conceptually by viewing elements as nested containers. You’ll understand how layouts work and how changes to one container affect those within it. This knowledge is essential for working with AI models and tools to fine-tune your prototypes and achieve exactly the look you want.

Another resource I strongly recommend is Excalidraw, a free web-accessible wireframing tool with virtually no learning curve. Think of it as a simplified version of Figma focused solely on rapid wireframing. AI models have gotten extremely good at processing visuals, and showing what your idea looks like helps the model better understand your expectations.

In this stage, I typically answer these questions and document them as crucial inputs for the model or tool to build a prototype that closely matches my vision:

What design aesthetic am I going for? (e.g., playful, quirky, professional, vibrant, muted, modern). Don’t hesitate to combine multiple design aesthetics to achieve a hybrid look.
What color palette will I use in my design system?
- What gradient palette will I use for my primary colors?
- What gradient palette will I use for my secondary colors?
- What gradients do I want for hover and click states?
- What primary and secondary colors will I use for backgrounds?
Tip: Use Coolors.co to generate and match color & gradient palettes and note down the hex codes in your look and feel documentation. I also recommend reading everything about colors from the Figma Design Basics guide mentioned earlier to help make decisions easier.
What effects do I want to implement? This is where I consider elements such as subtle animations on hover, fade in/out effects, skeleton loading states, drop shadows or glow effects on card elements, glassmorphism or transparency effects, and background blurs. These little touches separate good designs from great ones. Tip: As always, the key is achieving the right balance. Don’t add everything simply because you can. Sometimes, less is better. After a few prototyping iterations, you’ll begin to understand the sweet spot for achieving this balance.
Do I already have a design system that I can ask the tool to import for building a component library? Tip: Most enterprise settings have their own design systems that you can import into your VSCode project and have the model build out a full component library. If you’re building a personal project, I recommend starting with publicly available design systems such as Google’s Material Design (for fun, vibrant and professional design aesthetics) or IBM’s Carbon Design System (for muted, professional and elegant design aesthetics).
How do I want my forms to work?
- How will my forms launch (modals / sidebars / standalone)?
- What patterns do I want to support for form elements (calendars, single-choice, multi-choice options, lists, filtered lists, toggles, etc.)?
- What validations do I need to implement, and how will they activate (inline or post submission)?
- How will my edit flows work (inline editing / quick edits / full form-based edits / field-based edits)?
How is my application structured in terms of pages, organization of information and forms? What does my Information Architecture or Sitemap look like? Generally, I document the Information Architecture or Sitemap in an Excel document, starting with the landing page and then working top to bottom on each page. I then color code common elements (For example: a reference form that could be called from two different pages would be color-coded the same in both places).
How does the layout of content differ between web and mobile form factors?
- Example #1: Do content cards that appear side by side on the web layout stack vertically on mobile or display in a swipeable gallery layout?
- Example #2: How do flip effects on mouse hover in the web layout translate to mobile where there is no hover? What would the mobile UX look like instead?

These questions may seem overwhelming, and it’s not necessary to address all of them when starting out. What’s more important is having fun prototyping and getting comfortable with the process. Once you’re confident, start incorporating these elements into your workflow. As mentioned before: Start Small & Level Up.

Final Prep

After completing this exercise and answering these questions, I recommend starting a new chat with your preferred AI model (Gemini, ChatGPT, or Claude) and sharing this context as a Product Brief to identify any potential gaps in your planning.

A quick note: AI models process Markdown formatting more effectively than plain text. For best results, provide your instructions in Markdown format. You can reference this Markdown cheat sheet for guidance. Alternatively, consider using tools like Obsidian or Notion, which not only support Markdown exports and copy-to-clipboard functionality but also serve as repositories for your knowledge base, giving you the best of both worlds.

Here’s the template I use to validate my application vision and figure out any potential blind spots. This helps me prepare this document for the next stage.

# Your Role
You are an experienced Product Disovery team, comprising of a highly experience UX Design Lead, a highly experienced Product Manager with specific subject matter expertise in <ENTER_APP_DOMAIN_OR_OBJECTIVE_HERE> and a highly experienced Solutions Architect well versed in using the latest technology stack and effective system design and architectural patterns.

# Objective
I want to build an application prototype using <MODELS_HERE>. To do so, I plan on providing the project context in the **Product Brief** section. I'd like you to first process the overall context and understand what I want to build. I'd like you to then step through each point and synthesize how the information pertains to the overall objective. Using step-by-step reasoning, I'd like you to review the entire context and let me know if it has all the content required for <MODEL_HERE> to build the application prototype to specifications. Feel free to suggest corrections as well as recommend additional points that I may have missed out on. Once you confirm everything looks good, I will ask you to play another role and use this context to generate a master starter prompt that will get added into a .md file as project specifications for <MODEL_HERE> to reference for building the application.

>NOTE: At this point, I am not looking to build out the backend or build any integrations end to end. This will be a frontend focused application prototype only. So, do not provide any additions to the product brief about the backend aspects or integrations.

# Output Instructions
After reviewing the entire context provided in **Product Brief**, please return the revised product brief in the same format that I have entered. Preserve the existing format and structure, but feel free to modify and enhance the content. 
For example: If there are additional points that need to be added to the **Workflow** section, append the points to the appropriate section. Please feel free to convert any existing points to a tone or sequence that is more friendly to being processed by <MODEL_HERE>.

# Product Brief
## Application Overview
<INSERT_APPLICATION_OVERVIEW_HERE>
## Features
NOTE: Features marked as **Now** would be included in the first release. Features marked as **Next** would be added immediately after the initial release. Features marked as **Later** would be added in future releases.
<INSERT_APPLICATION_FEATURES_HERE>
## Workflows
NOTE: Workflows marked as **Now** would be included in the first release. Workflows marked as **Next** would be added immediately after the initial release. Workflows marked as **Later** would be added in future releases.
<INSERT_APPLICATION_WORKFLOWS_HERE>
## Target Segments & User Personas
NOTE: Target segments & personas marked as **Now** would be included in the first release. Target segments & personas marked as **Next** would be added immediately after the initial release. Target segments & personas marked as **Later** would be added in future releases.
### Target Segments
<INSERT_TARGET_SEGMENTS_HERE>
### User Personas
<INSERT_USER_PERSONAS_HERE>
## Key Jobs-To-Be-Done
<DOCUMENT_JOBS_TO_BE_DONE_HERE>
## UX Design & Design Principles
### Design Aesthetic
### Colors
### Effects
### Design System
### Information Architecture
### Form Behavior
### Validation Rules & Patterns

Concluding The Visualize Phase

Remember, AI models excel at processing visuals. Your wireframes, together with the document created during the Visualize phase, provide the model with crystal-clear understanding of what you want to build. This foundational work sets you up for success in the next stages.

For this article series, I’ve chosen to showcase the simplest prototype you can build: a personal website.

As a beginner, this is the ideal starting project for several reasons:

No data requirements
No complex flows to design, such as login or session management
No rule-based or validation-based forms
No market validation needed
Limited number of screens, allowing for multiple iterations and valuable learning experience with your tools that you can later apply to more complex prototypes

And of course, who doesn’t want to work on their personal website?

After completing my questionnaire, I spent just a few minutes building wireframes in Excalidraw. The landing page shown below took me exactly ten minutes to create. I recommend designing multiple variations if you want to evaluate different layouts, but at minimum, create two versions of each page: one for web and one for mobile. This approach saves significant time during the visual polish phase, as your initial build already closely matches your vision.

And with that, the Visualize phase is complete! In the next article in this series, I will go over the Strategize phase, which will outline how to get that killer starter prompt to whip up a functional prototype in record time.

Prototyping using Gemini & Claude – Part I

Sat, 31 May 2025 18:17:17 GMT

It is truly an exciting time to be in Product right now. The world of AI has dropped a whole new set of cheat codes into our laps, giving us incredible ways to accelerate our workflows and boost productivity. For me, the magic wasn’t just in automating tasks; it was in reclaiming my calendar. By simplifying my workflows with AI, I’ve been able to free up more time to speak with users or work with engineering teams to brainstorm on some of macro and micro aspects of the overall product delivery. In this series, I will explore some of these accelerators.

While one of the most basic accelerators I have explored is using AI to write PRDs and BRDs, I will jump ahead to one of the topics that has been the most transformative for me personally: The ability to rapidly prototype applications to gather early and frequent user feedback.

Over the past few months, I’ve gone down the rabbit hole exploring platforms like Lovable.Dev, Replit, and Bolt.New, alongside tools like Figma Make and GitHub CoPilot, all in the name of building rapid prototypes and gathering user feedback sooner.

While I plan to share a detailed comparison of these options in a future post, in this multi-part article I will focus on setting oneself up with the right mindset for rapid prototyping and leveraging the strengths of Gemini CLI & Claude Code at the same time for rapid prototyping.

After a number of trials with the other approaches outlined earlier, I found that the approach of using CLI (Command Line Interface) based tools like Gemini CLI and Claude Code provided me with the largest amount of the one superpower that one needs when prototyping applications using AI: Control.

When you’re a one-person band trying to spin up a new application prototype, you need to be the puppet master, able to tweak every detail at will. This is where Gemini CLI and Claude Code truly shine.

Think of them as a partner that has access to your entire codebase and understands your project inside and out. This approach allows you to scaffold and build a prototype from the ground up, giving you full command over the code. The result? You can iterate, fix, and improve things at lightning speed, shrinking your time to market.

Now, for the reality check: this method does have a steeper learning curve than its point-and-click cousins. If the thought of getting your hands dirty doesn’t make your eyes glaze over, then you’re in for a treat. Let’s dive in.

Depending on where you work, your organization may have different regulatory and compliance aspects limiting what options are available to you. This is true, especially in Enterprise settings and in that case I’d advise making a case to the powers that be to implement new tooling, or taking advantage of whatever is available.

There is no substitute for basics

Just like any other application build, the basic building blocks for getting an application prototype do not have a substitute and should be approached in the same way as one would approach an actual development lifecycle. The key difference here is in understanding that you are the product lead, the UX lead, the development lead and the test lead all rolled into one.

It is essential to have a clear product vision about what you want to build and a strategy for how you want to build it. Using coding assistants places us firmly in the Realize phase, takes us to Actualize and allows us to rapidly iterate and Crystallize based on user feedback.

This multi-part article will walk you through my methodology in leveraging CLI coding assistants within an application development framework and generate rapid prototypes.

So, what exactly are Gemini CLI & Claude Code?

Before we get into Gemini CLI & Claude Code, let’s understand some basics.

What is a Terminal?

Ever seen any troubleshooting guide or heard floor support asking you to press the Windows + R key on your keyboard and asking you to type in the command, “cmd”, or asking you to launch the command prompt? If yes, that is a terminal you launched. In Windows, it is called the Command Prompt.

A terminal, in the context of computing, is a software program that provides a text-based interface to interact with a computer’s operating system. It’s essentially a window where you can type commands to run programs, manage files, and perform various system tasks. This is in contrast to the graphical user interface (GUI) most people are used to, which relies on icons, windows, and a mouse.

Think of it like this: if your computer’s operating system is the engine of a car, the GUI is the dashboard with all its buttons and displays, while the terminal is like opening the hood and directly interacting with the engine components using specialized commands.

Why Use a Terminal?

While a graphical interface is often easier for everyday tasks, the terminal offers several advantages, especially for developers, system administrators, and power users:

Speed and Efficiency: For many tasks, typing a single command can be much faster than clicking through multiple menus and windows.
Automation: You can write scripts to automate repetitive tasks, saving a significant amount of time and effort.
Power and Flexibility: The command line provides access to a wide range of powerful tools and settings that may not be available through the GUI.

Modern operating systems all come with a terminal application. On macOS, it’s simply called Terminal. On Windows, you have the Command Prompt and the more modern Windows Terminal, which can run different shells like PowerShell & WSL (Windows subsystem for Linux).

Gemini CLI is an open-source command-line interface that brings the power of Google’s LLM (large language model), Gemini directly to your terminal. It allows developers and other users to interact with Gemini for a wide range of tasks, from coding and debugging to content creation and research, all within their familiar command-line environment.

Gemini Documentation: Official Google Documentation

Intro Video: Gemini CLI in 6 Minutes!

Claude Code is a powerful, agentic coding assistant developed by Anthropic that operates directly within your terminal. Unlike traditional code completion tools, Claude Code is designed to understand the full context of your codebase. This allows it to perform complex, multi-step tasks through natural language commands.

Claude Documentation: Official Claude Documentation

Intro Video: Introducing Claude Code

But, why do we need both? Why not use just one?

You’re probably wondering this and to be fair, I asked myself the same. At the very start, I wanted to evaluate the approach of using a CLI coding assistant to prototype an application and I landed in a bit of analysis-paralysis trying to decide on one assistant. But then, the thought struck me. Why not both? Now, this is not one of those gotchas where I answer a question of “Why?” with “Why Not?” I did a fair bit of reasoning and analysis and concluded that this would indeed be the best path forward.

Gemini CLI vs Claude Code – A Feature Comparison

Category	Gemini CLI	Rating	Claude Code	Rating
Cost & Accessibility	Free with Google account, 1,000 requests/day, 60/min	⭐⭐⭐⭐⭐	Requires Anthropic subscription, pay-per-use	⭐⭐⭐
Context Window	1M tokens – excellent for large codebases	⭐⭐⭐⭐⭐	~200K tokens – good for focused work	⭐⭐⭐⭐
Code Quality	Good for rapid prototyping	⭐⭐⭐	High-quality, production-ready code	⭐⭐⭐⭐⭐
Speed	Fast code generation	⭐⭐⭐⭐⭐	Moderate speed, prioritizes quality	⭐⭐⭐⭐
Error Handling	Basic error handling	⭐⭐⭐	Superior error handling & debugging	⭐⭐⭐⭐⭐
User Interface	Action boxes, summarized outputs	⭐⭐⭐⭐	Step-by-step announcements, readable format	⭐⭐⭐⭐⭐
Enterprise Features	Limited enterprise support	⭐⭐	Enterprise-level security & support	⭐⭐⭐⭐⭐
Documentation Quality	Standard documentation	⭐⭐⭐	Detailed, structured documentation	⭐⭐⭐⭐⭐
Learning Curve	Straightforward setup	⭐⭐⭐⭐⭐	Requires subscription setup	⭐⭐⭐⭐
Multi-file Analysis	Excellent cross-file relationships	⭐⭐⭐⭐⭐	Good for focused file work	⭐⭐⭐⭐
Code Architecture	Basic architectural insights	⭐⭐⭐	Strong architectural reasoning	⭐⭐⭐⭐⭐
Integration Capabilities	Good Google ecosystem integration	⭐⭐⭐⭐	Strong CLI integration, workflow focus	⭐⭐⭐⭐⭐
Debugging Support	Basic debugging assistance	⭐⭐⭐	Advanced debugging & troubleshooting	⭐⭐⭐⭐⭐
Code Review Quality	Surface-level reviews	⭐⭐⭐	Thorough, detailed code reviews	⭐⭐⭐⭐⭐
Performance Optimization	Basic optimization suggestions	⭐⭐⭐	Advanced performance insights	⭐⭐⭐⭐⭐

Overall Ratings

Tool	Overall Score	Best For
Gemini CLI	⭐⭐⭐⭐ (4.0/5)	Rapid prototyping, learning, cost-conscious development
Claude Code	⭐⭐⭐⭐⭐ (4.5/5)	Production code, enterprise projects, quality-focused development

In conclusion, while I could’ve achieved a lot of what I wanted to using Gemini CLI, I didn’t want to sell myself short and wanted to use the best of both worlds to not only generate an app prototype rapidly, but also ensure that the underlying code could be productionized with minimal churn.

In the next article, I will document how I used Claude and Gemini, not only in the Realize phase, but also in the Visualize and Strategize phase to document my vision and implementation plan. I’ll end this article however with a quick installation guide in case anyone’s interested in getting this setup up and running.

Step-by-Step Setup Guide (for Windows)

Step 1: Install Visual Studio Code and Extensions

Download and Install VS Code: Go to https://code.visualstudio.com/ Download and install VS Code for Windows
Install Essential Extensions: Open VS Code Go to Extensions (Ctrl+Shift+X) Install these extensions: WSL (by Microsoft) – to connect VS Code to your WSL environment Claude Code – Find and install the Claude Code extension from the marketplace

Step 2: Set Up Your Development Environment

Open WSL in VS Code: Open VS Code Press Ctrl+Shift+P to open command palette Type “WSL: New WSL Window” and select it This opens VS Code connected to your WSL environment
Install Shell Command for VS Code (if not already done): Press Ctrl+Shift+P Search for “Shell Command: Install ‘code’ command in PATH” Run this command

Step 3: Authentication Setup

If you haven’t authenticated Claude Code yet:

Get Your API Key: Go to https://console.anthropic.com/ Create an account or log in Navigate to API Keys section Generate a new API key Important: Keep this key secure and never share it
Authenticate Claude Code: In your WSL terminal, run: claude Follow the prompts to enter your API key Choose your preferred color theme

Step 4: Install Claude Code

# In WSL terminal
npm install -g @google/gemini-cli
gemini auth
# Follow authentication with Google account

Step 7: Configure Both Extensions

Claude Code Setup:

# In VS Code integrated terminal
claude
# Extension auto-installs
# Use Ctrl+Esc to launch directly from editor

Gemini Code Assist Setup:

Click Gemini icon in VS Code activity bar
Sign in with Google account
Accept privacy notice
Enable agent mode toggle for advanced features

Gemini CLI Setup:

# In VS Code integrated terminal
gemini
# Follow on screen prompts for any additional configurations

Step 6: Create Project with Dual AI Context

mkdir my-app-prototype
cd my-app-prototype

Now, perform the below steps:

Open VSCode in your project directory (or create a new folder for your website project)
Create the claude.md file: Right-click in the Explorer panel → “New File” Name it claude.md (exactly this name – it’s what Claude Code looks for) Or use Ctrl+N to create a new file and save it as claude.md
Add the content: Copy the entire enhanced description from the md file that Claude generated above Paste it into your claude.md file Save the file (Ctrl+S)
Create the GEMINI.md file: Right-click in the Explorer panel → “New File” Name it GEMINI.md (exactly this name – it’s what Claude Code looks for) Or use Ctrl+N to create a new file and save it as GEMINI.md

Whew! And that’s it! In the next article, we will go over what needs to be added to the claude.md and gemini.md files to get truly set up to start prototyping. But for that, we need to start with the Visualize and Strategize phase.

If you found this article helpful, drop in a comment; I’d love to discuss!