opencode-scheduler: Instructions file for Codex

Agent-Native Architecture: Implementation Guide

A practical reference for building applications where agents are first-class citizens.

---

Core Principles

1. Parity

Whatever the user can do through the UI, the agent must be able to achieve through tools.

Create a capability map:

User Action	Agent Method
Create item	write_file or create_item tool
Update item	update_file or update_item tool
Delete item	delete_file or delete_item tool
Search	search_files or search tool

Test: Pick any UI action. Can the agent accomplish it?

2. Granularity

Prefer atomic primitives. Features are outcomes achieved by an agent in a loop.

# Wrong - logic in code
Tool: classify_and_organize_files(files)

# Right - agent decides
Tools: read_file, write_file, move_file, list_directory, bash
Prompt: "Organize downloads by content and recency"

Test: To change behavior, do you edit prose or refactor code?

3. Composability

New features = new prompts (when tools are atomic and parity exists).

Prompt: "Review files modified this week. Summarize changes. Suggest three priorities."

No code written. Agent uses list_files, read_file, and judgment.

4. Emergent Capability

Agent can accomplish things you didn't explicitly design for.

Build atomic tools → Users ask unexpected things → Agent composes solutions → You observe patterns → Optimize common patterns → Repeat.

---

Tool Design

Domain Tools

Add when needed for:

1. Vocabulary anchoring - create_note teaches "note" concept better than "write file with format"
2. Guardrails - Validation that shouldn't be left to agent judgment
3. Efficiency - Common multi-step operations

Rule: One conceptual action per tool. Judgment stays in prompts.

# Wrong
analyze_and_publish(input)  # bundles judgment

# Right
publish(content)  # one action, agent decided what to publish