Skip to content

SPEC.md

Latest commit

 

History

History
122 lines (92 loc) · 3.34 KB

SPEC.md

File metadata and controls

122 lines (92 loc) · 3.34 KB

Agent Repo Standard Spec

This spec defines a minimal, consistent way for agents and humans to coordinate work inside a code repository.

1) Core principle

  • Humans read Markdown summaries.
  • Automation reads JSON run records.
  • Agents must update both.

This keeps daily review simple while enabling reliable audit, replay, and dashboards.

2) Required files

2.1 AGENTS.md

A contract for agent behavior in this repo. It MUST define:

  • where tasks live
  • how "done" is determined
  • what checks to run (prefer Makefile targets)
  • where to write run records

2.2 STATUS.md

A one-page snapshot of current work. It SHOULD NOT contain full history.

Required sections:

  • Now
  • Active
  • Blockers
  • Last update

2.3 TASKS.md

A task list with stable task IDs.

Task ID format:

  • T-001, T-002, etc.

Required sections:

  • Doing
  • Next
  • Done

Each task entry MUST include:

  • ID
  • status keyword in brackets: [todo] [doing] [blocked] [done]
  • a short title
  • definition of done (DoD) or acceptance criteria (at least 1 bullet)
  • a Run: link once work starts or completes

2.4 .agent/runs/<run_record>.json

One JSON file per agent run.

File name format:

  • YYYY-MM-DDThh-mm-ssZ_<task_id>.json Example:
  • 2025-12-11T22-18-05Z_T-001.json

Required fields:

  • run_id (string, same as filename without extension is recommended)
  • task_id (string, T-###)
  • objective (string)
  • status (string enum: planned | in_progress | completed | failed | canceled)
  • started_at (ISO 8601 string)
  • ended_at (ISO 8601 string or null)
  • files_changed (array of strings)
  • commands_run (array of strings)
  • tests_passed (boolean or null)
  • notes (array of strings)

Optional fields:

  • diff_summary (string)
  • risks (array of strings)
  • follow_ups (array of strings)
  • links (object, any helpful URLs)

2.5 .agent/index.json

A rollup index for tooling.

Suggested fields:

  • last_updated_at
  • latest_run_id
  • runs_total
  • runs_completed
  • runs_failed
  • last_success_run_id
  • last_failed_run_id

This file may be generated by automation.

3) Makefile as the agent tooling API

The repo SHOULD provide these targets:

  • help (default)
  • setup
  • fmt
  • lint
  • test
  • ci (runs fmt, lint, test)

Agents SHOULD prefer Make targets over ad hoc commands.

4) Definition of done (recommended)

A task is done when:

  • make ci passes, or a clear explanation exists in the run record
  • TASKS.md is updated with completion timestamp and run link
  • STATUS.md reflects the new state

5) Markdown conventions (recommended)

  • Use GitHub Flavored Markdown task checkboxes.
  • Keep STATUS.md short, 1 screen.
  • Keep tasks atomic, prefer 30-120 minutes per task.

6) Compatibility notes (Codex, MCP, tracing)

This repo standard is compatible with common agent tooling patterns:

  • Codex style agents can use AGENTS.md as the primary instruction contract.
  • Codex CLI writes its own session logs under CODEX_HOME (often ~/.codex) in date-sharded JSONL files; this is separate from .agent/.
  • MCP (Model Context Protocol) can be used to give an agent standardized access to tools and extra context; this is optional and orthogonal to the file conventions here.
  • If you orchestrate agents using the OpenAI Agents SDK, you can also rely on built-in tracing for detailed event logs; .agent/ remains your repo-local done state and run summary.