Skip to content

AGENTS_EX.md

Latest commit

 

History

History
293 lines (213 loc) · 12.5 KB

AGENTS_EX.md

File metadata and controls

293 lines (213 loc) · 12.5 KB
Raw

— Agent Working Guide

Overview

Quick Start

# Install dependencies
# TODO: e.g. npm install / pip install -r requirements.txt / cargo build

# Run tests
# TODO: e.g. npm test / pytest / cargo test --workspace

# Start local server
# TODO: e.g. npm run dev / uvicorn app.main:app --reload

# Lint / typecheck
# TODO: e.g. npm run lint / ruff check . / cargo clippy

Build & Verification Commands

Command What it checks Speed
fast
fast
slow

Repository Structure

<!-- TODO:
src/           Application source
docs/          Project docs and task queue
  INDEX.md        Documentation navigation map
  PRD.md          Product requirements and scope
  ARCHITECTURE.md System topology and boundaries
  CONVENTIONS.md  Coding standards and patterns
  DECISIONS.md    Architectural decision log
  ENV_VARS.md     Environment variable matrix
  TESTING.md      Test strategy and inventory
  workboard.json  Canonical task queue
  workboard.schema.json JSON Schema for task queue
  workboard.md    Workboard field definitions and usage rules
tests/         Test suite
scripts/       Utility scripts
.claude/       Claude harness config (skills/ — synced, do not edit here)
.agents/       Codex harness config (skills/ — synced, do not edit here)
.codex/        Codex harness config (skills/ — synced, do not edit here)
               Keep only the directories your harness actually uses.
               Edit skill sources in ag.dev and re-run the sync.
-->

Docs navigation: docs/INDEX.md

Architecture

Full topology, component responsibilities, data flow, and deployment targets: docs/ARCHITECTURE.md

Code Style & Constraints

Never

  • Never commit secrets or credentials.
  • Never bulk-rewrite docs/workboard.json; use targeted edits only.

Always

  • Always run the fast verification suite before marking a task done.
  • Always update relevant docs/ files when behavior changes.

Patterns

Full convention guide: docs/CONVENTIONS.md

Maintaining Docs

Docs must stay current with the code. Update the relevant doc in the same commit as the code change — never defer a doc update to a follow-up task.

What changed Doc to update
System topology, services, auth, data flow, deployment docs/ARCHITECTURE.md
Coding pattern, naming rule, or never/always constraint docs/CONVENTIONS.md
Env var added, removed, renamed, or changed docs/ENV_VARS.md
New architectural question raised docs/DECISIONS.md — add OPEN-XX
Architectural decision resolved docs/DECISIONS.md — move to Resolved
Test file added, removed, or pattern changed docs/TESTING.md
Product scope, users, or success criteria changed docs/PRD.md
Any doc added, removed, renamed, or moved docs/INDEX.md — always
Constraint or gotcha discovered during a task This file (AGENTS.md) — append to Discoveries

Rule: If a section in AGENTS.md summarizes something, and the full doc changes, update both the summary here and the full doc in the same commit.

Workboard

The canonical task queue is docs/workboard.json. Schema and usage contract: docs/workboard.md. Machine validation schema: docs/workboard.schema.json.

Inspect it with the query-workboard skill; execute a task end-to-end with start-task. Never dump the full board into context — use targeted jq queries.

A task is startable when:

  • status == "todo"
  • blocked_by is empty or missing
  • all depends_on tasks have status == "done"

Targeted edit rules:

  • Never rewrite the full workboard.json.
  • Only update the status fields of the task currently being worked.
  • Roll back in_progress → todo if blocked mid-task and unresolved.

Agent Workflow

Standard task cycle for this project:

  1. Read this file (AGENTS.md / CLAUDE.md) at the start of every session.
  2. Invoke query-workboard to find the next startable task.
  3. Invoke start-task to execute it (reads docs, implements, verifies, updates board).
  4. Update this file if you discovered a constraint, pattern, or pitfall worth encoding.
  5. Commit changes. Summarize: what was done, what was skipped, what is next.

For multi-task runs, invoke ralphloop wrapping start-task with an iteration count.

Invoking Skills

Skills live in a per-harness directory and are invoked by name with your harness's own command prefix — / in Claude Code, $ in Codex. This file deliberately names skills without a prefix, because AGENTS.md and CLAUDE.md are the same file and cannot carry both. Use whichever your harness expects.

Stopping Conditions

Stop and report (do not continue) when:

  • No startable task exists (all are blocked or done).
  • A verification command fails and the fix is not obvious.
  • An irreversible action (migration, destructive write, external publish) is required and the task does not explicitly authorize it.

Debugging & Gotchas

Environment Variables

See docs/ENV_VARS.md for the canonical variable and secret matrix.

Testing

Full test strategy, file inventory, and patterns for writing new tests: docs/TESTING.md

Deployment

Living Document

This file is a running notebook of agent discoveries. After each task cycle, update this file if you found:

  • A constraint that would have saved time if it were written here.
  • A debugging tip that resolves a non-obvious failure.
  • A pattern that should be followed for consistency.
  • A "never do X" rule that emerged from a near-miss.

Append under ## Discoveries below. Keep each entry to 2–3 sentences with a date. Do not reorganize or rewrite existing entries — append only.

### YYYY-MM-DD — <short title>
<What you found and why future agents working here should know it.>

Discoveries