Convention Over Configuration

A3S Code's convention-over-configuration capability is not a separate runner. It is a durable-agent composition built from filesystem-first conventions, the session runtime, tool permissions, multi-agent delegation, resumable orchestration, HITL, run replay, and the serve scheduler. It turns an agent from "a chat-capable SDK session" into a work unit with a role, tools, collaborators, state, and takeover points.

If you are evaluating directory-first agent frameworks, treat A3S Code as a lower-level and more embeddable runtime. Directory conventions, tools, connections, child agents, schedules, persistence, and observability are all present, but they are not tied to one frontend channel or deployment platform. A host can connect them to managed sessions, open-platform APIs, AHP, MCP, A3S Box, or its own task system.

Capability Map

Minimal Shape

An interactive team agent can start from a normal repository:

repo/
├── agent.acl
├── AGENTS.md
├── .a3s/
│   ├── agents/
│   │   ├── release-reviewer.md
│   │   ├── security-reviewer.md
│   │   └── verification-runner.md
│   └── skills/
│       └── release-readiness.md
└── src/

agent.acl controls models, providers, parallelism, and automatic delegation:

default_model = "provider/model-id"
max_parallel_tasks = 4
auto_parallel = false

providers "provider" {
  apiKey = env("PROVIDER_API_KEY")
  baseUrl = env("PROVIDER_BASE_URL")

  models "model-id" {
    tool_call = true
    limit = {
      context = 128000
      output = 4096
    }
  }
}

agent_dirs = ["./.a3s/agents"]

auto_delegation {
  enabled        = true
  min_confidence = 0.72
  max_tasks      = 4
  auto_parallel  = false
}

The host starts a session and wires in skills, agent directories, persistence, and delegation policy:

import { Agent } from '@a3s-lab/code';

const agent = await Agent.create('agent.acl');

const session = agent.session('/repo', {
  builtinSkills: true,
  skillDirs: ['./.a3s/skills'],
  agentDirs: ['./.a3s/agents'],
  autoDelegation: { enabled: true, minConfidence: 0.72, maxTasks: 4 },
  maxParallelTasks: 8,
  autoParallel: false,
  autoSave: true,
});

const result = await session.send(`
Prepare a release-readiness check:
1. Ask the exploration role to find high-risk changes.
2. Ask the security role to inspect permissions, secrets, and external side effects.
3. Ask the verification role to list required regression commands.
4. Merge everything into a blocker-first report.
`);

console.log(result.text);
console.log(result.verificationSummaryText);

Agent Directory Shape

Use a filesystem-first agent when you need long-running behavior, schedules, or directory-scoped tools:

release-agent/
├── instructions.md
├── agent.acl
├── skills/
│   └── release-readiness.md
├── schedules/
│   └── daily.md
└── tools/
    ├── github.md
    └── search-auth.md

instructions.md is the role slot:

You are a release-readiness agent for this repository.
Always separate blockers from follow-up work.
Never invent versions or CI status. Read evidence from the workspace.

schedules/daily.md is a recurring turn:

---
cron: "0 9 * * *"
name: daily-release-check
enabled: true
---
Summarize merged changes since the last run, inspect release risks,
and report only blockers plus required verification.

serve_agent_dir creates an independent session for every schedule. With a SessionStore, restart reloads the current directory config and tools while recovering prior context from the store.

Tools And Connections

A3S Code exposes tools in three layers:

Tools are not unlimited just because a file exists. Visibility, permission gates, HITL, allow-lists, and sandboxing are controlled by the harness or the AgentDir loader. Give high-privilege tools only to trusted directories, and inject secrets through environment variables and host connections.

Subagents And Teams

A convention-first subagents/ concept maps to three A3S Code entry points:

Automatic delegation depends on agent descriptions and confidence scoring. It fits "the user describes the goal and the runtime chooses specialists." Fixed release flows, batch reviews, and migrations are better expressed explicitly with orchestration.

Observability And Takeover

Long-running agents must be observable and interruptible. A3S Code's core observation surfaces are:

• stream() for incremental events.
• runs(), runSnapshot(), and runEvents() for active and historical runs.
• toolNames() / toolDefinitions() for the visible tool surface.
• activeTools() for currently running tool-call snapshots.
• cancelRun(runId) to interrupt an active turn.
• traceEvents() for compaction, delegation, tools, and verification evidence.
• verificationSummaryText for release or review gates.

A host platform can translate those events into WebSocket/SSE streams, audit records, debug panels, and workflow node states.

Relationship To A3S Box

A3S Code owns the agent loop, tools, delegation, state, and verification. A3S Box owns stronger runtime isolation: MicroVMs, OCI workloads, networking, and TEE. If "the model may run shell, but the process must be isolated" is a requirement, run the tool execution through A3S Box or expose isolated capabilities through AHP/MCP.

Typical composition:

A3S Code session
  -> permission policy and HITL
  -> AHP or MCP tool adapter
  -> A3S Box isolated workload
  -> typed result and verification evidence

When To Use It

Use this shape for:

• Long-running engineering agents for release checks, dependency upgrades, and repository maintenance.
• Work that naturally splits into explore / review / verify / implement roles.
• Automatic delegation with retained permission gates, auditability, and verification evidence.
• Cron-based reports with recoverable context.
• Agents that need to connect to managed workflows, hosted sessions, or external collaboration channels.

Avoid it when:

• A single deterministic API call is enough; use a tool contract instead.
• The task requires full GUI automation but has no structured tool interface; provide MCP/AHP or browser tools first, then let A3S Code schedule them.
• The task needs strong OS-level isolation but only has a local shell enabled; integrate A3S Box.

Reading Order

1. Filesystem-First
2. Agent Directory
3. agents/ Role Directory
4. tools/ Tool Directory
5. schedules/ Schedule Directory
6. Tasks
7. Teams