Skip to content

AGENTS.md

Latest commit

 

History

History
139 lines (105 loc) · 5.98 KB

AGENTS.md

File metadata and controls

139 lines (105 loc) · 5.98 KB
Raw

AGENTS.md — Universal Agent Instructions

Works with: Claude Code, Cursor, Codex, OpenClaw, Windsurf, and any AI coding agent.

FIRST MESSAGE — Boot Sequence

Before your first response, run this command and display its full output:

atris atris.md

This is the Atris boot sequence. Show the output to the user, then respond naturally.

Core Files

Atris is the source of truth. This file is only an adapter for tools that read AGENTS.md; do not turn it into a parallel brain. Durable policy, workflow, task truth, proof, review, and backend/cloud sync all flow through Atris.

File Purpose
atris/atris.md Protocol/backbone for this workspace
atris/PERSONA.md Communication style (read first)
atris task Current tasks, claims, dialogue, proof
.atris/state/tasks.projection.json Readable task projection for UIs/agents
atris/TODO.md Rendered/legacy task view only
atris/MAP.md Navigation (where is X?)

Agent Contract

Every agent should leave four artifacts another agent can trust:

Artifact Where
Objective atris task note <id> "Goal / files / done / check"
Navigation atris/MAP.md when a new route or file location is learned
Change Small git diff in declared files only
Proof ready atris task ready <id> --proof "<commands or receipt>"
Human accept atris task accept <id>

Do not rely on chat context. Put the task, file pointers, and proof on disk. Do not write new operating doctrine here first; add it to Atris policy, skills, wiki, or atris/atris.md, then regenerate this adapter if needed.

How to Report

The human approves work by reading, so how you report IS the product. Rules:

  • Results are capabilities. State what someone can do now that they couldn't before, then what it means for them or the business. Tests are one word ("verified"); the meaning is the sentence. Shape: "We did X, so you can now Y." Detail stays under the hood; the reader asks if they want more.
  • Three results, air between them, rest on ask. A report fits one screen with no scrolling. Reading it is one glance.
  • Stake first, then the move. "Agents burn tokens hand-rolling parsers: add one shared view." Plain words; flags, ids, and identifiers belong in the body, never the headline.

Native goals and task approval are separate gates:

Agent proof ready -> native goal can complete
Human accept      -> task Done + AgentXP awarded

Always-on agents should move proof-backed work to Review, complete their native goal, then continue the mission loop with the next goal. They must not run atris task accept or claim AgentXP unless a human approved the proof.

Mission-shaped user intent wins before normal task selection. If the user message starts with atris mission run, execute that command first, then run atris mission goal --json and mirror goal.visible_goal into the native chat goal. If the user asks for a mission, loop, overnight run, "keep going", "fix this", or sends a screenshot with task intent and no mission exists yet, start one with atris mission run "<inferred objective>" --owner <member> instead of falling back to manual task/worktree flow.

Task owners are functional or feature members, not engines. Use task-planner, architect, mission-lead, validator, launcher, or a feature owner for assignment; put coding agent models like Codex and Claude in the executed_by section.

Workflow

PLAN  → atris plan   (break ideas into tasks)
BUILD → atris do     (execute tasks)
CHECK → atris review (verify + cleanup)

Worktrees

Default to the current checkout for small, clean, single-agent fixes. Use atris worktree start only when the launcher is dirty, multiple agents may edit in parallel, proof will run for a long time, the change is risky, or release/publish work needs a clean tree. Use atris worktree cleanup to preview merged worktree removal and atris worktree cleanup --apply to remove clean merged worktrees.

Mission Autonomy

Use atris mission when work should survive this chat or run as an autonomous loop.

member -> mission start --verify -> status --status active -> one bounded step -> mission tick --verify -> receipt -> complete|run|stop
  • Start current-agent work: atris mission start "<objective>" --owner <member> --runner codex_goal --lane code --verify "<cmd>" --stop "<condition>"
  • Start headless Claude work: add --runner claude --cadence "15m" --always-on, then use atris mission run <id> --max-ticks 4 --complete-on-pass.
  • Resume: atris mission status --status active --json, then pick the mission matching your owner/member.
  • Prove: after one bounded step, run atris mission tick <id> --verify --summary "<what changed>".
  • Close: if the verifier passes, run atris mission complete <id> --proof "<receipt_path>"; if current-agent work should keep going, repeat status -> step -> tick.

Rules

  • 3-4 sentences max per response
  • Use ASCII visuals for planning
  • Check MAP.md before touching code
  • Run atris task list or atris task next before picking work
  • Claim tasks with atris task claim <id> --as <functional-member>
  • Move agent-completed work to Review via atris task ready <id> --proof "..."
  • Complete native Codex/Claude goals after proof is in Review, so always-on work can continue
  • Only use atris task accept <id> when the human has approved the proof
  • Keep durable learning in Atris-owned policy/skill/wiki/task state; keep AGENTS.md as a generated/pointer layer
  • Treat atris/TODO.md as a rendered view; do not manually use it as the source of truth
  • Use the real business slug from local Atris state; do not hardcode private slugs in generated docs

Anti-patterns

  • Don't explore codebase manually (use MAP.md)
  • Don't skip visualization step
  • Don't leave stale tasks
  • Don't hand-edit TODO.md for active task ownership
  • Don't write verbose docs

Protocol: See atris/atris.md for full spec.