7 phút đọcagents

Tri Agent-Native Standard

agent-nativecliworkflow
Mục lục

Version: 0.1
Date: 2026-06-22
Owner: Tri Vo
Status: Published

Purpose

This standard defines how Tri’s tools, repositories, CLIs, and agent workflows should be designed so that humans and AI agents can work on the same system safely, clearly, and repeatably.

The goal is not to make tools “AI-assisted” as an afterthought. The goal is to make the system agent-native from the start: legible to humans, operable by agents, auditable through files and git, and reversible when something goes wrong.

Core Principle

Agent-native means:

A capable agent can understand the workspace, choose the right primitive actions, execute them through stable interfaces, report progress, and leave behind a clear audit trail that a human can review or revert.

CLI-first is a strong foundation, but it is not enough by itself. A CLI becomes agent-native only when it also supports context, parity, composability, safety, observability, and rollback.

Design Layers

1. File-First, Git-Backed

Prefer files as the shared interface between human and agent.

Use files for:

  • Content
  • Drafts
  • Configuration
  • Policies
  • Logs
  • Context
  • Templates

Use git as the audit trail whenever possible.

Rules:

  • Important agent changes should be represented as file diffs.
  • Content should be readable without a proprietary UI.
  • A human should be able to inspect, edit, revert, or cherry-pick agent work.
  • Generated work should avoid hidden state unless the hidden state is mirrored in a readable file.

Examples:

  • src/content/links/*.md
  • src/content/posts/*.md
  • inbox/*.md
  • AGENTS.md
  • agent-log/*.md

2. Draft Before Public

The default agent behavior is preview or draft, not publish.

Rules:

  • /zk <url> means preview and analysis only.
  • draft means create a non-public artifact.
  • publish, đăng luôn, or a similarly explicit instruction means public release is allowed.
  • Public actions must be reported with final URLs and verification status.

Recommended flow:

/mt link preview <url>
/mt link draft <url>
/mt link publish <slug> --confirm

For public-facing repositories:

  • draft: true by default for agent-created content.
  • draft: false only after explicit approval.
  • If direct publish is allowed, the command should make that clear.

3. Every Public Action Has a Rollback

Any command that changes public state must have an obvious reverse path.

Required pairs:

/mt link publish <slug>
/mt link unpublish <slug>

/mt post publish <slug>
/mt post unpublish <slug>

/mt deploy promote <id>
/mt deploy rollback <id>

Rules:

  • Publish without unpublish is incomplete.
  • Delete should prefer reversible archive/trash behavior.
  • Destructive actions require confirmation or --force.
  • Non-interactive destructive actions require explicit confirmation flags.

4. CLI Is the Agent API

The CLI is the stable operating contract for both humans and agents.

Rules:

  • The CLI should expose the real product model, not internal implementation details.
  • Commands should be readable as human workflows.
  • Every important command should support machine-readable output.
  • The CLI should work without a UI.

Good:

/mt link preview https://example.com
/mt link draft https://example.com --repo mtri-site
/mt link publish wc2026-live-hub --confirm

Avoid:

/mt create --type link --mode live --strategy auto --target src/content

5. Human-Readable and Machine-Readable Output

Every important command should have two output modes:

  • Human mode for terminal use.
  • Machine mode for agents and scripts.

Human output should answer:

  • What changed?
  • Where is the file?
  • What is the current state?
  • What is the next suggested action?
  • What URL or artifact should be checked?

Machine output should be stable:

/mt link draft <url> --json

Example JSON:

{
  "status": "drafted",
  "path": "src/content/links/example.md",
  "slug": "example",
  "draft": true,
  "next": "/mt link publish example --confirm"
}

Output rules:

  • Primary output goes to stdout.
  • Diagnostics, progress, and errors go to stderr.
  • Support --json for structured output.
  • Support --plain for stable line-based output when useful.
  • Respect NO_COLOR, TERM=dumb, and --no-color.

6. Primitive First, Workflow Later

Build small reliable primitives before creating high-level automation.

Primitive commands:

/mt link fetch <url>
/mt link extract <url>
/mt link preview <url>
/mt link draft <url>
/mt link publish <slug>
/mt link verify <slug>
/mt link unpublish <slug>

Workflow commands can come later:

/mt link save <url>
/mt weekly-links build
/mt newsletter draft-from-links

Rules:

  • Do not hide too much judgment inside one giant command.
  • Make each primitive idempotent when possible.
  • Let agents compose primitives into new workflows.
  • Promote repeated human requests into workflow commands only after the pattern is proven.

7. Context Is Product State

Agents need local context before action.

Each important workspace should include an agent-readable context file.

Recommended files:

  • AGENTS.md for operating rules.
  • README.md for human overview.
  • context.md or docs/agent-context.md for current policy and conventions.
  • CHANGELOG.md or agent-log/*.md for notable changes.

Context should define:

  • Default behavior.
  • Approval policy.
  • File structure.
  • Naming conventions.
  • Draft/publish rules.
  • Style and tone.
  • Rollback instructions.
  • Known risks.

Example policy:

## Publishing Policy

Agents may create drafts without approval.
Agents must not publish public content unless Tri explicitly says "publish", "đăng", or "public luôn".
After publishing, agents must verify the live URL and report the commit.

8. Visible Progress, No Silent Mutation

Agents should not silently mutate important files or public state.

For multi-step work, report:

  • What is being inspected.
  • What decision was made.
  • What files will be changed.
  • What has been committed.
  • What has been verified.

Progress states:

previewed -> drafted -> committed -> deployed -> verified

Rules:

  • Before editing, state the intended edit.
  • After editing, state the changed file.
  • After public deploy, verify the live URL.
  • If verification fails, say so clearly and give the current state.

9. Approval Based on Stakes and Reversibility

Approval requirements depend on risk.

Low-risk and reversible:

  • Reading files.
  • Searching.
  • Creating local drafts.
  • Creating non-public notes.
  • Running harmless validation.

Usually okay without explicit approval.

Medium-risk:

  • Committing to a repository.
  • Creating a pull request.
  • Editing shared docs.
  • Changing config.

Proceed when the user’s intent is clear; report the action.

High-risk:

  • Publishing public content.
  • Sending messages as the user.
  • Posting to social media.
  • Emailing external people.
  • Deleting or overwriting important data.
  • Money, legal, health, or security actions.

Require explicit approval.

Rule of thumb:

If it leaves the machine, affects other people, or is hard to undo, confirm first.

10. Parity Map

Agent-native systems need parity between human capabilities and agent capabilities.

For each entity, map the full lifecycle.

Example for link:

capture -> preview -> draft -> edit -> publish -> verify -> unpublish -> archive

The CLI should expose each lifecycle stage.

Parity checklist:

  • Can the human do this in UI or git?
  • Can the agent do the same through a stable tool?
  • Can the result be inspected as a file?
  • Can the action be reversed?
  • Can the output be consumed by another tool?

11. Composability

Agent-native tools should work together.

Rules:

  • Commands should accept stdin where useful.
  • Commands should produce output that another command can consume.
  • Support --json for structured chaining.
  • Support stable slugs and IDs.
  • Avoid hidden UI-only state.

Example:

/mt link extract <url> --json \
  | /mt link draft --stdin --repo mtri-site \
  | /mt link verify --stdin

12. Error Handling and Recovery

Errors should help humans and agents recover.

Rules:

  • Validate early.
  • Fail with actionable messages.
  • Avoid raw stack traces by default.
  • Use predictable exit codes.
  • For expected failures, suggest the next command.

Default exit codes:

0 success
1 generic failure
2 invalid usage or validation error
3 missing dependency
4 authentication or permission failure
5 network or remote service failure
6 verification failed

Example:

Error: live URL returned 404 after deploy.
State: committed, not verified.
Next: run `/mt link verify wc2026-live-hub` or check Cloudflare Pages deploy.

CLI Design Standard

Every CLI spec should include:

  1. Name
  2. One-liner
  3. Command tree
  4. Usage synopsis
  5. Args and flags
  6. Output contract
  7. Error and exit code map
  8. Safety rules
  9. Config and env precedence
  10. Examples
  11. Rollback commands
  12. Agent-readable --json examples

Default global flags:

-h, --help
--version
-q, --quiet
-v, --verbose
--json
--plain
--dry-run
--no-input
--no-color

Config precedence:

flags > env vars > project config > user config > system config

Example: /mt command

One-Liner

/mt manages Tri’s personal site content through a file-first, git-backed, agent-native workflow.

Command Tree

/mt link preview <url>
/mt link draft <url>
/mt link publish <slug> --confirm
/mt link verify <slug>
/mt link unpublish <slug>
/mt link list

/mt post draft <source>
/mt post publish <slug> --confirm
/mt post verify <slug>
/mt post unpublish <slug>

/mt note draft <source>
/mt note publish <slug> --confirm

/mt site status
/mt site deploy
/mt site verify

Publishing Flow

/mt link preview https://example.com
/mt link draft https://example.com --repo mtri-site
/mt link publish example --confirm
/mt link verify example

Safe Default

If the user gives a URL without saying publish:

/mt link preview <url>

If the user says “save this”:

/mt link draft <url>

If the user says “publish this”:

/mt link publish <slug> --confirm

Agent Operating Rules

Agents working under this standard must:

  1. Read workspace context before acting.
  2. Prefer preview or draft before publish.
  3. State intended edits before making them.
  4. Use stable CLI/tool interfaces instead of UI automation when available.
  5. Keep changes file-first and auditable.
  6. Use --json when chaining tools.
  7. Verify public URLs after deployment.
  8. Report commit IDs and file paths.
  9. Provide rollback options after public changes.
  10. Never silently publish public content unless explicitly instructed.

Maturity Levels

Level 0: Manual

Only humans can operate the system. Agent must click UI or guess.

Level 1: Scriptable

There are scripts, but they are inconsistent and undocumented.

Level 2: CLI-Friendly

There is a usable CLI with help, flags, and stable commands.

Level 3: Agent-Friendly

The CLI has --json, --dry-run, predictable output, and clear errors.

Level 4: Agent-Native

The system has context files, parity maps, draft/publish policy, rollback commands, progress states, audit trail, and verified outcomes.

Target for Tri systems: Level 4.

References