Agentify Any App

agentify-adoption-guide.svg

agentify-any-app.md

Agentify Any App

By Darryl Wong

A pattern for turning an existing application into an agent-operable product.

This is an idea file and build manual. It is designed to be pasted into an LLM agent such as Codex, Claude Code, OpenCode, Hermes, OpenClaw, NanoClaw, or another agent framework. The goal is to communicate the architecture and operating model clearly enough that the agent can inspect a target app, propose the right integration points, and help build the first agentified workflow in collaboration with the user.

This image is a human adoption guide. Agents should use the written sections below as the source of truth.

Agent Operating Instructions

Use this section as the operating brief when applying this document to a target app.

When given this document and access to a target app:

1. Inspect the app's routes, API layer, permission model, data model, and primary workflows.
2. Identify one high-value workflow that can be agentified first.
3. Produce an API and URI surface map for that workflow.
4. Define context, read, dry-run, validation, and write actions.
5. Draft one or more agent skills around those API and URI contracts.
6. Draft or update agent core files that define global rules, permissions, confirmations, logging, and sub-agent routing.
7. Propose a minimal sub-agent architecture only if the workflow benefits from role separation.
8. Define a permission matrix that maps users, roles, resources, and agent actions.
9. Add an audit and observability plan.
10. Produce an MVP implementation plan with acceptance criteria and test coverage.

Do not assume the agent may bypass the app. The app remains the system of record and the enforcement point for authentication, authorization, validation, business rules, persistence, and audit logging.

Do not create a parallel business-logic path for agents. Agent-facing APIs must call the same domain services, validation rules, authorization checks, persistence logic, and audit pipeline used by the human UI or public product APIs.

Core Idea

Agentifying an app does not mean bolting a chatbot onto the UI.

It means exposing a controlled app control surface through stable URIs and typed APIs, then teaching agents how to operate those surfaces through skills, core rules, permission checks, confirmations, and audit logs.

The target state:

• Users describe outcomes in natural language.
• The agent resolves the active app context.
• The agent plans a workflow using documented skills.
• The agent reads and writes through approved APIs.
• The app enforces permissions and validation.
• Risky operations require human confirmation.
• Every meaningful action is logged.
• Sub-agents can be introduced for role segregation when needed.
• Human-interface blockers are identified and removed from the normal execution path.

Preparation Vs Authority

A useful agent can prepare work without owning final authority.

The app should distinguish:

• Preparation: create drafts, upload files, apply structured changes, validate, preview, summarize, route, and stage work.
• Authority: send, submit, approve, publish, pay, delete, sign, invite, or otherwise make the work official.

Agents should usually be allowed to prepare and validate. The system of record should decide when prepared work may become official, using normal authorization, policy checks, review gates, and human approval where needed.

For high-risk workflows, final authority should be enforced by the app across every execution surface, not only by agent instructions.

Minimum Trust Gate

Most apps should not start with fully autonomous writes. The first reliable agentified version should prove this ladder:

Read -> Draft/Stage -> Preview -> Approval-Gated Execute -> Readback/Audit

This is the minimum trust gate:

• Read: the agent can inspect scoped app context through approved APIs.
• Draft or stage: the agent can prepare work without making it official.
• Preview: the app can show the exact proposed change, diff, or consequence.
• Approval-gated execute: high-risk writes require explicit user approval enforced by the app.
• Readback and audit: the agent verifies final state from the system of record and records evidence.

Treat direct autonomous mutation as a later maturity level, not the default MVP.

Non-Negotiables

• The app remains the authority.
• Agents operate through typed contracts, not hidden UI assumptions.
• Every read and write is authorized against the current actor, tenant, role, resource, and action.
• Agent APIs reuse existing domain logic instead of duplicating business rules.
• High-risk blocked states are enforced across UI, regular API, agent API, tools, and background flows.
• High-risk writes require explicit user confirmation.
• Material writes should support preview, dry-run, idempotency, and auditability.
• Skills must be plain-language enough for humans and structured enough for agents.

Human-Interface Blockers

Most existing apps were built for humans, not agents. Many workflows depend on a person clicking through screens, reading visual state, copying values, uploading files, or making decisions inside the app UI. These steps are human-interface blockers.

A human-interface blocker is any workflow step the agent cannot complete through typed APIs, context endpoints, canonical URIs, approved actions, or structured human-in-the-loop responses.

The target state is not "the agent tells the user where to click." The target state is:

• The agent completes the normal workflow through app-controlled APIs.
• Human UI operation is treated as a gap to remediate, not an acceptable default.
• If human input is required, the human responds through the agent flow where possible.
• If visual inspection is required, the agent supplies a deep link for quick confirmation and resumes from the confirmation result.

Common fixes:

• Add context APIs for information that only appears in the UI.
• Add action APIs for operations that only exist as buttons or forms.
• Add dry-run or preview endpoints for risky changes.
• Add validation endpoints for checks humans currently do manually.
• Add canonical URIs and deep links for quick visual review.
• Add structured confirmation prompts so users approve through the agent instead of manually continuing the app workflow.

Human-in-the-loop decision model:

Situation	Preferred path
Approval, risky write, missing data, or business judgment	Agent-side structured confirmation
Layout, rendering, chart, uploaded file, or visual state inspection	App deep link for quick visual confirmation
Missing API for a required operation	Treat as a blocker and define the required API/action fix
User must manually click through the app to continue	Treat as a blocker unless explicitly scoped as a temporary fallback

The agent should resume from the user's answer, confirmation token, uploaded evidence, or visual-confirmation result. It should not ask the user to complete hidden workflow steps manually and then guess what happened.

Action Surface Maturity

An action is not agent-ready just because the happy-path API exists. The action surface should also account for follow-up flows that human users normally handle inside the app.

Check whether each agent-facing action can handle:

• Wizards, modals, multi-step forms, and intermediate review screens.
• Validation errors, missing fields, policy blocks, and partial failures.
• Background jobs, delayed processing, status polling, and retry-safe completion.
• Uploaded files, attachments, generated reports, exports, and rendered previews.
• External sends, submissions, invitations, payments, signatures, or publications.
• System-generated IDs, URLs, messages, and other outputs needed by later steps.

Unsupported action chains are agentification blockers. Do not treat browser automation as the normal way to complete them.

Architecture

There are nine layers.

1. App Control Surface

The app exposes controlled surfaces that agents can inspect and manipulate.

This includes:

• Stable resource URIs.
• Context APIs.
• Read APIs.
• Dry-run APIs.
• Validation APIs.
• Write/action APIs.
• Permission APIs.
• Audit APIs.

The agent should operate against these surfaces instead of clicking through the UI like a human.

Agent surfaces should be thin orchestration endpoints. They should not reimplement business logic. A safe implementation usually looks like this:

agent action API -> auth/delegation check -> existing domain service -> existing validation -> existing persistence -> audit event

If the app already has stable public or internal APIs that enforce the correct rules, prefer wrapping or documenting those APIs instead of creating a second agent-only API.

2. URI And Resource Model

URIs give agents stable handles for app state.

Use "URI" to mean a canonical app resource identifier, not necessarily a browser route or API URL.

Define these separately:

Term	Meaning	Example
Canonical resource URI	Stable identifier agents use in plans, skills, logs, and permissions	app://tenant_123/invoices/inv_123
Browser route	Human-facing route in the web app	/invoices/inv_123
API path	HTTP endpoint used to fetch or mutate data	/api/invoices/inv_123
Deep link	URL that opens the app to a resource	https://app.example.com/invoices/inv_123

Examples:

app://{tenantId}/customers/{customerId}
app://{tenantId}/invoices/{invoiceId}
app://{tenantId}/projects/{projectId}/tasks/{taskId}
app://{tenantId}/workflows/{workflowId}/runs/{runId}

URIs should resolve to structured context:

GET /api/agent/context?uri=app://tenant_123/invoices/inv_123

The response should tell the agent what the resource is, what state it is in, what actions are available, and what permissions apply for the current user.

URI rules:

• Canonical URIs must include tenant or workspace scope when the app is multi-tenant.
• URI parsing must normalize and validate identifiers before use.
• A valid URI does not imply permission. Always authorize after resolving it.
• URI versions should be explicit when resources or workflows have breaking schema changes.
• Resource context should include a resource version, timestamp, or ETag so writes can detect stale state.

3. Agent API Layer

The API layer gives agents controlled actions.

Example actions:

GET  /api/agent/context?uri=app://tenant_123/invoices/inv_123
POST /api/agent/actions/invoice.validate
POST /api/agent/actions/invoice.prepare_approval
POST /api/agent/actions/invoice.submit_for_approval
POST /api/agent/actions/invoice.attach_support

Each action should define:

• Action name.
• Purpose.
• Input schema.
• Output schema.
• Required permissions.
• Confirmation level.
• Validation rules.
• Failure modes.
• Audit fields.
• Actor and delegation rules.
• Idempotency behavior for writes.
• Resource version or concurrency requirements.

Action execution rules:

• Every action must identify the effective actor.
• Every action must identify the tenant or workspace.
• Every action must evaluate permissions server-side.
• Every material write should require an idempotency key.
• Every material write should accept an expected resource version or equivalent concurrency guard.
• Every high-risk write should require a confirmation token or approval reference.
• Every action should return a machine-readable result and a human-readable summary.

4. Auth, Delegation, And Actor Model

The agent must act as an authorized actor, not as an undefined superuser.

Define these concepts:

Concept	Meaning
actorUserId	The human user accountable for the request
agentId	The agent or runtime executing the workflow
tenantId	The tenant, workspace, or organization scope
delegationId	A time-bound grant allowing the agent to act for a user or role
effectivePermissions	The permissions after tenant, user, role, resource, policy, and delegation checks
confirmationId	A user approval record required for high-risk actions

Delegation rules:

• Prefer acting as the current user for user-initiated work.
• Use service actors only for explicitly designed system workflows.
• Delegations must be scoped by tenant, actor, allowed actions, resources, expiry, and revocation state.
• Agent action logs must include both the human accountable actor and the agent executor.
• A missing, expired, revoked, or insufficient delegation must stop execution.

5. Skill Layer

Skills are operational manuals for agents.

A skill explains:

• Which workflow it covers.
• Which URIs it can operate on.
• Which APIs it may call.
• What inputs it needs.
• What outputs it should produce.
• What permissions are required.
• What must be confirmed by the user.
• How to handle errors.
• What good execution looks like.
• Which actor and delegation model it expects.
• Which actions are read-only, draft-only, or material writes.

The agent framework may vary, but the skill should remain readable as plain Markdown.

6. Agent Framework Layer

Frameworks such as OpenClaw, NanoClaw, Hermes, or another orchestration layer can run the skills.

The framework should:

• Load skills and core files.
• Interpret the user request.
• Resolve current app context.
• Create an execution plan.
• Call approved app APIs.
• Route to sub-agents when appropriate.
• Request user confirmation for risky actions.
• Persist execution history.

The app should avoid hard-coupling to one framework too early. Stable URI, API, permission, and audit contracts make the system portable across runtimes.

Define a minimal runtime adapter contract before integrating a framework:

interface AgentRuntimeAdapter {
  loadSkills(scope: { tenantId: string; userId: string; uri?: string }): Promise<Skill[]>;
  resolveContext(uri: string): Promise<AgentContext>;
  plan(request: UserRequest, context: AgentContext, skills: Skill[]): Promise<AgentPlan>;
  callAction(action: AgentActionCall): Promise<AgentActionResult>;
  requestConfirmation(request: ConfirmationRequest): Promise<ConfirmationResult>;
  writeAuditEvent(event: AgentAuditEvent): Promise<void>;
}

If a framework does not support this shape directly, build a small adapter rather than leaking framework-specific assumptions into the app.

7. Core Files

Core files define rules inherited by all skills and sub-agents.

They should cover:

• Global safety rules.
• API authentication.
• URI resolution.
• Permission policy.
• Confirmation policy.
• Logging and audit requirements.
• Error handling.
• Skill discovery.
• Sub-agent routing.
• Data privacy constraints.
• Runtime adapter contract.
• Auth and delegation model.
• Human-interface blocker policy.

Examples:

AGENTS.md
agent-core.md
skills/index.md
skills/invoice-approval.md
permissions/agent-permission-matrix.md
logs/agent-action-log.md

8. Sub-Agent Layer

Sub-agents are optional. Add them when the workflow benefits from specialization, separation of duties, or independent review.

Common roles:

• Context agent: gathers and summarizes app state.
• Planning agent: turns a user request into workflow steps.
• Validation agent: checks data quality, completeness, and policy compliance.
• Execution agent: calls approved APIs.
• Review agent: checks proposed changes before write operations.
• Audit agent: records what happened and explains the outcome.
• Domain agent: handles a specialized area such as invoices, CRM, support, finance, HR, or operations.

Use sub-agents deliberately. A simple MVP may only need one agent and one skill.

Default to one agent for the MVP unless there is a clear separation-of-duty reason.

For larger apps, keep one user-facing orchestrator and route to specialist agents behind the scenes. Specialist agents should be bound to app permissions, domain boundaries, and allowed action sets.

Sub-agent protocol:

• Each sub-agent must have a named role, allowed actions, and forbidden actions.
• Handoffs must include task, context references, expected output, and stop conditions.
• Sub-agents should not grant permissions to each other.
• Execution agents should not approve their own high-risk writes.
• Review agents should inspect proposed changes, not silently execute them.
• Shared memory should store references and summaries, not broad sensitive data dumps.
• Circular delegation should be rejected.

9. Enterprise Permission Layer

For enterprise use, agent permissions must map directly to user, tenant, role, and resource permissions.

Controls to define:

• Tenant isolation.
• User-to-agent delegation.
• Role-based action access.
• Resource-level authorization.
• Read/write separation.
• Approval thresholds.
• Skill enablement by user group.
• Admin controls.
• Audit trail by user, agent, skill, API action, and resource.

Example bundle assignment:

User group	Enabled skills
Sales	CRM updates, proposal drafting, follow-up planning
Finance	Invoice validation, reconciliation, reporting
Managers	Review, approval, escalation
Admins	Configuration, user management, skill enablement

Implementation Workflow

Use this workflow when agentifying a new app or adding a new agentified workflow.

Step 1. Inventory The App

Inspect:

• Frontend routes.
• Backend APIs.
• Data models.
• Auth and RBAC.
• RLS or database policies.
• Existing audit logs.
• Core user workflows.
• High-friction manual processes.

Output:

• App surface map.
• Workflow candidates.
• Permission model summary.
• Risk notes.

Step 2. Pick The First Workflow

Choose one workflow that is:

• Painful.
• Repeatable.
• High-value.
• Easy to measure.
• Bounded enough for an MVP.
• Safe enough to run with confirmations.

Good first workflows often involve preparing, validating, summarizing, drafting, classifying, routing, or reconciling.

Step 3. Define URI Coverage

Document the resources the agent must understand.

Example:

## URI Surface

| Canonical URI | Browser route | Resource | Purpose | Required context |
| --- | --- | --- | --- | --- |
| `app://{tenantId}/invoices/{invoiceId}` | `/invoices/:invoiceId` | Invoice | Primary workflow object | vendor, amount, status, PO, attachments |
| `app://{tenantId}/vendors/{vendorId}` | `/vendors/:vendorId` | Vendor | Validate vendor details | name, tax ID, bank status |
| `app://{tenantId}/purchase-orders/{poId}` | `/purchase-orders/:poId` | Purchase order | Match invoice to PO | amount, line items, approval status |

Step 4. Map And Remove Human-Interface Blockers

Walk through the workflow step by step and identify where the agent would still need a human to operate the app UI.

For each blocker, document:

• Current human UI action.
• Why the agent cannot complete it through existing APIs or context.
• Required agent-ready replacement.
• Missing context API, action API, dry-run endpoint, validation endpoint, canonical URI, or deep link.
• Whether the fallback is structured confirmation, visual confirmation, or blocked until the app is changed.

Output:

• Human-interface blocker catalog.
• Required API/context/action fixes.
• Temporary human-in-the-loop fallback rules.
• Confirmation and deep-link requirements.

Step 5. Define Auth And Delegation

Before defining write actions, define who the agent acts as and how authorization is evaluated.

Document:

• User authentication method.
• Agent authentication method.
• Tenant or workspace scope.
• Whether the agent acts as the current user, a delegated actor, or a service actor.
• Delegation expiry and revocation.
• Confirmation token creation and verification.
• Permission checks for each action.

Output:

• Actor model.
• Delegation policy.
• Confirmation policy.
• Permission decision flow.

Step 6. Define Agent APIs

Create read, context, dry-run, validation, and write actions. These APIs should call existing domain services instead of reimplementing business logic.

Prefer this shape:

## Action: invoice.prepare_approval

- Method: `POST`
- Path: `/api/agent/actions/invoice.prepare_approval`
- Purpose: Validate an invoice and prepare approval notes without submitting.
- Risk level: medium
- Confirmation required: no, because it only creates a draft
- Blocked by missing API: no
- Human interface fallback: none
- Visual confirmation deep link: optional
- Required permission: `invoice:update`
- Actor model: current user or valid delegation
- Domain service: `InvoiceApprovalService.prepareApproval`
- Idempotency: required for persisted drafts
- Concurrency: requires `expectedResourceVersion`
- Input:
  - `invoiceId: string`
  - `tenantId: string`
  - `resourceUri: string`
  - `expectedResourceVersion?: string`
  - `idempotencyKey?: string`
  - `instructions?: string`
- Output:
  - `status: "ready" | "blocked"`
  - `draftNotes: string`
  - `missingItems: string[]`
  - `recommendedNextAction: string`
- Audit fields:
  - `actorUserId`
  - `agentId`
  - `skillId`
  - `resourceUri`
  - `actionName`
  - `inputHash`
  - `outputHash`

Step 7. Add Dry-Runs And Confirmations

Every material write should have a dry-run or preview path.

Example:

POST /api/agent/actions/invoice.submit_for_approval/preview
POST /api/agent/actions/invoice.submit_for_approval

Confirmation levels:

Level	Examples	Required behavior
Low	search, summarize, classify, explain	can run directly
Medium	prefill, draft, prepare, validate	create staged output
High	submit, delete, pay, invite, publish, approve, permission changes	require explicit user confirmation

High-risk writes should require a server-issued confirmation token:

preview -> user reviews diff -> confirmation token created -> write action verifies token -> audit event records confirmation

Visual confirmation should follow this path:

agent supplies deep link -> user inspects app state -> user responds in agent UI -> agent records confirmation result -> agent resumes through APIs

Step 8. Add Readback Verification

After material agent writes, read the resource back from the system of record and verify that the expected state actually exists.

Readback verification should check:

• Resource ID and canonical URI.
• Resource version or timestamp.
• Status or review state.
• Expected field count, attachment count, or changed values.
• Required approval, pending, or blocked state.
• Any system-generated URLs, IDs, or metadata the next step depends on.

If the primary tool response omits important details, use an approved read API, context API, or system-of-record endpoint to verify non-secret metadata before proceeding.

Step 9. Write The Skill

Create a skill that teaches the agent how to operate the workflow.

Use the skill template in this document.

Step 10. Update Core Files

Define global agent rules before adding many skills.

At minimum, core files should tell agents:

• Which APIs are allowed.
• How to authenticate.
• How to resolve URIs.
• How to request confirmation.
• How to log actions.
• How to handle permission denials.
• How to stop when the operation is unsafe.
• How to perform readback verification.
• How to keep skill instructions synchronized with live APIs and tools.

Step 11. Define The Runtime Adapter

Before choosing or integrating a specific framework, define the adapter between the app and the runtime.

Output:

• Skill loading contract.
• Context resolution contract.
• Action call contract.
• Confirmation contract.
• Audit event contract.
• Error and retry contract.

Step 12. Add The Collaboration UI

The best default UI is a context-aware side panel plus inline affordances near the workflow.

The UI should show:

• Current resource context.
• Agent plan.
• Evidence used.
• Proposed changes.
• Before-and-after diff.
• Confirmation controls.
• Deep links for visual confirmation when structural context is insufficient.
• Errors and blockers.
• Final outcome.

The agent UI should augment the app workflow, not replace the core interface. When a human-in-the-loop step is required, the user should respond through the agent flow wherever possible.

Step 13. Add Tests And Evaluation

Test:

• Permission enforcement.
• Delegation expiry and revocation.
• Tenant isolation.
• Human-interface blocker detection.
• Structured confirmation and visual confirmation fallbacks.
• API validation.
• Dry-run versus write behavior.
• Confirmation gates.
• Idempotency behavior.
• Stale resource versions.
• Readback verification after material writes.
• Review-gate enforcement across all execution surfaces.
• Audit log completeness.
• Agent skill examples.
• Runtime adapter behavior.
• UI loading, empty, error, and success states.
• Mobile and desktop responsiveness.
• Accessibility.

Step 14. Iterate And Generalize

Only generalize after one workflow works end to end.

Then extract shared patterns:

• Common action schema.
• Common context response.
• Skill template.
• Permission matrix.
• Audit schema.
• UI plan/review components.
• Human-interface blocker catalog.
• Sub-agent routing rules.
• Readback verification pattern.
• Sanitized validation evidence template.

Maintain skill and tool alignment:

• Update skills when commands, endpoints, schemas, or tool names change.
• Update smoke tests with the same change that modifies agent-visible surfaces.
• Mark legacy commands clearly or remove them.
• Record only sanitized validation evidence.

Required Outputs

When an agent uses this gist to agentify an app, it should produce portable artifacts first and repo-specific planning artifacts only when the target repository expects them.

Universal Artifacts

These apply to most apps:

agent/README.md
agent/core.md
agent/runtime-adapter.md
agent/skills/index.md
agent/skills/<workflow-skill>.md
agent/api/context-contract.md
agent/api/action-catalog.md
agent/auth/actor-and-delegation-model.md
agent/workflows/human-interface-blockers.md
agent/permissions/permission-matrix.md
agent/audit/audit-schema.md
agent/evidence/sanitized-validation-evidence.md
agent/ui/collaboration-ui-notes.md
agent/tests/agentification-checklist.md

Optional Repo Planning Artifacts

Use these only when the repo has a planning convention that expects them:

devplan/masterPRD.md
devplan/featurePRD_##.md
devplan/devplan_##.md
devplan/todo_##.md

For an existing repo, adapt paths and filenames to local conventions.

Templates

App Surface Map Template

# App Surface Map

## Primary Routes

| Browser route | Canonical URI pattern | Resource | User goal | Agent relevance |
| --- | --- | --- | --- | --- |

## Existing APIs

| Method | Path | Domain service | Purpose | Auth required | Agent-safe? |
| --- | --- | --- | --- | --- | --- |

## Data Models

| Model | Important fields | Permissions | Agent notes |
| --- | --- | --- | --- |

## Candidate Workflows

| Workflow | User pain | Risk | MVP fit |
| --- | --- | --- | --- |

Human-Interface Blocker Catalog Template

# Human-Interface Blocker Catalog

| Workflow step | Current human UI dependency | Why it blocks the agent | Required fix | HITL fallback | Priority |
| --- | --- | --- | --- | --- | --- |
| Review invoice PDF | User opens attachment and visually checks totals | Attachment contents are not exposed as structured context | Add document extraction context and deep link to attachment | Visual confirmation through agent with app deep link | high |
| Submit invoice | User clicks submit button in app | No approved submit action API exists | Add `invoice.submit_for_approval` action with preview and confirmation token | Blocked until API exists | high |

Agent Context API Template

{
  "canonicalUri": "app://tenant_123/invoices/inv_123",
  "browserRoute": "/invoices/inv_123",
  "deepLink": "https://app.example.com/invoices/inv_123",
  "tenantId": "tenant_123",
  "resourceType": "invoice",
  "resourceId": "inv_123",
  "resourceVersion": "v17",
  "displayName": "Invoice INV-123",
  "state": {
    "status": "draft",
    "amount": 1200,
    "currency": "USD"
  },
  "actor": {
    "id": "user_123",
    "type": "user",
    "role": "finance_manager"
  },
  "agent": {
    "id": "agent_invoice_approval",
    "runtime": "framework-neutral"
  },
  "delegation": {
    "id": "delegation_123",
    "expiresAt": "2026-07-03T01:00:00Z",
    "allowedActions": [
      "invoice.validate",
      "invoice.prepare_approval",
      "invoice.submit_for_approval"
    ]
  },
  "permissions": {
    "canRead": true,
    "canUpdate": true,
    "canSubmit": true,
    "canDelete": false
  },
  "availableActions": [
    "invoice.validate",
    "invoice.prepare_approval",
    "invoice.submit_for_approval"
  ],
  "relatedUris": [
    "app://tenant_123/vendors/vendor_123",
    "app://tenant_123/purchase-orders/po_123"
  ]
}

Action Catalog Template

# Agent Action Catalog

## Action: `<domain>.<verb>`

- Method:
- Path:
- Domain service called:
- Purpose:
- Risk level:
- Confirmation required:
- Blocked by missing API:
- Human interface fallback:
- Visual confirmation deep link:
- Readback verification required:
- Review gate surfaces:
- Required permission:
- Allowed roles:
- Actor model:
- Delegation required:
- Tenant scoped:
- Idempotency required:
- Concurrency guard:
- Dry-run/preview path:
- Input schema:
- Output schema:
- Validation rules:
- Failure modes:
- Readback verification:
- Review gate enforcement:
- Audit fields:
- Example request:
- Example response:

Runtime Adapter Template

# Agent Runtime Adapter

## Purpose

Define the boundary between the app and the selected agent framework.

## Adapter Methods

| Method | Purpose | Input | Output | Notes |
| --- | --- | --- | --- | --- |
| `loadSkills` | Load skills available to actor and URI | tenant, actor, uri | skills | Must respect skill enablement policy |
| `resolveContext` | Resolve canonical URI to scoped context | uri, actor | context | Must authorize reads |
| `plan` | Create a plan from user request and context | request, context, skills | plan | Must mark risky actions |
| `callAction` | Call approved app action | action call | result | Must enforce permissions server-side |
| `requestConfirmation` | Ask user to approve risky action | proposed change | confirmation result | Must produce confirmation record |
| `writeAuditEvent` | Record event | event | void | Must be append-only |

## Framework Notes

Document how the selected runtime maps to this adapter. Keep framework-specific assumptions here, not inside app business logic.

Skill Template

# Skill: <Workflow Name>

## Purpose

## Supported URIs

## Allowed APIs

## Inputs

## Outputs

## Required Permissions

## Actor And Delegation Model

## Human-Interface Blockers

## Confirmation Rules

## Readback Verification

## Operating Procedure

1. Resolve the current URI.
2. Fetch agent context.
3. Validate permissions.
4. Confirm no required workflow step depends on unmodeled human UI operation.
5. Build a plan.
6. Confirm the resource version is current.
7. Run dry-run or validation actions.
8. Present staged changes to the user.
9. Request structured or visual confirmation when required.
10. Execute approved actions with idempotency keys.
11. Read back the resource from the system of record and verify expected state.
12. Log outcome.

## Failure Modes

## Recovery Behavior

## Example User Requests

## Example API Calls

## Acceptance Criteria

Core File Template

# Agent Core Rules

## Scope

## Global Safety Rules

- Never bypass app authentication.
- Never bypass app authorization.
- Never create a parallel agent-only business logic path.
- Never perform high-risk writes without explicit confirmation.
- Never rely on human app UI operation as the normal execution path.
- Prefer dry-run and preview actions before writes.
- Stop when required context or permission is missing.
- Log all material actions.
- Use idempotency keys for material writes.
- Check resource versions before writes when supported.

## API Authentication

## Actor And Delegation Model

## URI Resolution

## Permission Policy

## Confirmation Policy

## Audit Policy

## Skill Loading

## Runtime Adapter

## Sub-Agent Routing

## Data Privacy

## Error Handling

Permission Matrix Template

# Agent Permission Matrix

| Role | Resource scope | Skill | Read | Draft | Validate | Submit | Approve | Delete | Delegation allowed | Notes |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| User | Own records | invoice-approval | yes | yes | yes | no | no | no | no | |
| Manager | Team records | invoice-approval | yes | yes | yes | yes | yes | no | yes | |
| Admin | Tenant records | configuration | yes | yes | yes | yes | yes | conditional | yes | Delete requires separate policy |

Audit Log Template

{
  "timestamp": "2026-07-03T00:00:00Z",
  "requestId": "req_123",
  "sessionId": "session_123",
  "tenantId": "tenant_123",
  "actorUserId": "user_123",
  "agentId": "agent_invoice_approval",
  "delegationId": "delegation_123",
  "skillId": "invoice-approval",
  "runtime": "framework-neutral",
  "resourceUri": "app://tenant_123/invoices/inv_123",
  "resourceVersionBefore": "v17",
  "resourceVersionAfter": "v18",
  "actionName": "invoice.submit_for_approval",
  "riskLevel": "high",
  "confirmationId": "confirm_123",
  "confirmationSummary": "User approved submitting invoice INV-123 for manager review.",
  "policyDecision": {
    "allowed": true,
    "matchedRules": [
      "invoice:submit",
      "tenant:member",
      "delegation:valid"
    ]
  },
  "idempotencyKey": "idem_123",
  "previousStateHash": "sha256:...",
  "proposedStateHash": "sha256:...",
  "finalStateHash": "sha256:...",
  "inputHash": "sha256:...",
  "outputHash": "sha256:...",
  "status": "success",
  "error": null,
  "errorCategory": null
}

Sanitized Validation Evidence Template

# Sanitized Validation Evidence

## Test Run

- Date:
- Environment:
- Workflow:
- Agent/runtime:
- Skill version:
- App/API version:

## Actions Tested

| Action | Resource ID or URI | Expected result | Actual result | Status |
| --- | --- | --- | --- | --- |

## Safety Results

- Review or approval state:
- Send/write/finalization status:
- Blocked paths tested:
- Readback verification result:
- Secrets exposed: no
- Raw client payloads stored: no

## Notes

Record only sanitized metadata such as IDs, statuses, URLs safe to share, validation results, and high-level workflow names. Do not include raw secrets, credentials, private client documents, mailbox payloads, or full uploaded files.

MVP Path

The smallest useful version:

1. Choose one workflow.
2. Define one primary URI.
3. Add one context API.
4. Add three to five action APIs.
5. Include at least one draft or staging action.
6. Include at least one dry-run or preview action.
7. Require approval-gated execution before high-risk writes.
8. Write one skill.
9. Write one core file.
10. Add a simple side panel for plan review.
11. Read back and verify material writes.
12. Log all material actions.

Minimum trust gate:

Read -> Draft/Stage -> Preview -> Approval-Gated Execute -> Readback/Audit

Example MVP:

Workflow: Prepare invoice for approval
URI: app://{tenantId}/invoices/{invoiceId}
Skill: invoice-approval
Actions:
  - invoice.get_context
  - invoice.validate
  - invoice.prepare_approval
  - invoice.submit_for_approval.preview
  - invoice.submit_for_approval

Safety Rules

• The app remains the source of truth.
• The app enforces authentication and authorization.
• The agent only calls approved APIs.
• Agent APIs must call existing domain services or approved public/internal APIs.
• Browser/UI handoff is a fallback for confirmation or inspection, not the normal execution path.
• The agent should not use browser automation when a typed API exists.
• The agent should not infer permissions from UI visibility alone.
• High-risk blocked states should be enforced across UI, regular API, agent API, tools, and background flows.
• High-risk writes require explicit user confirmation.
• Dry-run actions should be preferred before writes.
• Material writes should be read back from the system of record before the agent claims completion.
• Permission failures should stop execution.
• Expired, revoked, or missing delegations should stop execution.
• Audit logs should be append-only.
• Sensitive data should be minimized in prompts, logs, and skill examples.

Agentification Lint Checklist

Run this checklist before calling a workflow agent-ready.

• Every supported resource has a stable URI.
• Canonical URIs distinguish resource IDs from browser routes and API paths.
• Every workflow step has been checked for human-interface blockers.
• No workflow step requires unmodeled human UI operation for normal execution.
• Each remaining human-in-the-loop step is classified as structured confirmation, visual confirmation, or blocked pending API work.
• Every agent action has an input and output schema.
• Every agent action maps to an existing domain service or approved API path.
• Every action surface accounts for follow-up flows such as wizards, validation errors, background jobs, attachments, reports, and external sends.
• Every write action has an explicit permission requirement.
• High-risk actions require confirmation.
• High-risk review gates are enforced across all available execution surfaces.
• Dry-run or preview exists for material writes.
• Material writes support idempotency keys.
• Material writes check resource versions or equivalent concurrency guards.
• Material writes have readback verification criteria.
• Actor, tenant, agent, delegation, and confirmation IDs are modeled explicitly.
• Context APIs return only relevant scoped data.
• Skill docs list allowed APIs and confirmation rules.
• Skill docs, helper commands, MCP/tools, and API schemas are version-aligned.
• Core files define safety, permission, logging, and error behavior.
• Runtime adapter boundaries are documented before framework-specific code is added.
• Audit logs include user, agent, skill, action, resource, policy decision, confirmation, and outcome.
• Sanitized validation evidence exists for smoke tests or critical workflows.
• Tests cover allowed, denied, and confirmation-required paths.
• Tests cover expired delegation, tenant isolation, idempotency, and stale resource versions.
• The UI shows plan, evidence, proposed change, confirmation, and result.
• Visual confirmation deep links are provided when structural context is insufficient.
• The agent resumes from human confirmation results instead of asking the user to manually complete app workflow steps.
• The workflow works on desktop and mobile.
• Accessibility target is WCAG 2.1 AA with a Lighthouse or equivalent score of at least 90.

Agentification Evaluation Checklist

Use this compact evaluation before calling a workflow ready for real users.

Scenario	Expected result
Allowed read	Scoped context is returned through an approved API
Allowed draft or stage	Prepared work is saved or returned without becoming official
Unapproved high-risk mutation	Request is blocked before execution
Approved high-risk mutation	Action executes exactly as approved and no more
Wrong record, wrong user, or excessive scope	Request is denied by server-side authorization
Stale approval, expired delegation, or stale resource version	Request is denied or forced back to preview
Readback after material write	System-of-record state matches the approved outcome
Audit evidence	Logs capture actor, agent, action, resource, policy decision, confirmation, and outcome without leaking secrets

Open Questions

Design Principles

• Use APIs for execution and the UI for collaboration.
• Keep permissions server-enforced.
• Separate agent preparation from app-controlled authority.
• Make planned actions inspectable before execution.
• Keep agent context narrow and relevant.
• Prefer typed tools over browser or DOM automation.
• Build for auditability from the first version.
• Start with one workflow, then generalize the action framework.
• Keep skills readable as plain Markdown.
• Keep the app framework-neutral until a runtime proves itself.

What Good Looks Like

An app is meaningfully agentified when:

• A user can ask for an outcome, not just click a button.
• The agent can resolve the relevant app resource.
• The agent can explain its plan.
• The agent can prepare or execute work through approved APIs.
• The agent does not depend on hidden human UI operation for normal execution.
• Human-interface blockers are cataloged and either remediated or explicitly treated as temporary fallbacks.
• The app, not the agent prompt, controls final authority for high-risk outcomes.
• The agent verifies important writes by reading back from the system of record.
• The user can inspect and approve risky changes.
• The app enforces all permissions.
• The audit log explains what happened.
• Sanitized validation evidence proves the workflow without exposing secrets or raw client payloads.
• The skill documentation is clear enough for a new agent to operate the workflow in a future session.

Related Guides

• API-to-Agentification Workflow - decide per capability whether to reuse, harden, extend, build, or block.
• Repository Agent Brief: Plan How to Open an API - inspect a repository and produce the API architecture and delivery plan.

Use the workflow when an application has no supported API or when its existing APIs are insufficient for safe agentic use.