Skip to content

AGENTS.md

Latest commit

 

History

History
68 lines (53 loc) · 4.01 KB

AGENTS.md

File metadata and controls

68 lines (53 loc) · 4.01 KB
Raw

AGENTS.md — loa

Agent-driven software-development framework. This file is the portable, tool-agnostic projection of loa's governance and conventions, read first by AGENTS.md-aware tools. Tool-specific depth lives in CLAUDE.md / .claude/. Source of truth: those files — this is a generated summary.

Quick Start

Primary interface: 49+ commands fronted by 5 Golden Path commands (zero-arg).

/loa
/plan
/build
/review
/ship
  • /loa — where am I? status + health + next step
  • /plan — requirements → architecture → sprints
  • /build — implement the current sprint
  • /review — code review + security audit
  • /ship — deploy + archive the cycle

Commands

5 Golden Path commands (/loa, /plan, /build, /review, /ship) front 49 total commands (truenames). See PROCESS.md for the full list; type /loa for orientation.

Project Governance

Precedence: NEVER > MUST > ALWAYS > SHOULD > MAY. These are mechanically enforced (harness disallowed-tools + PreToolUse hooks), not advisory.

NEVER

  • NEVER write application code outside /implement (OR a construct with declared workflow.gates), and NEVER reach implementation except via /run sprint-plan, /run sprint-N, or /bug against an existing sprint plan (OR when a construct with declared workflow.gates owns the current workflow)
  • NEVER use Claude's TaskCreate/TaskUpdate for sprint task tracking when beads (br) is available
  • NEVER skip /review-sprint and /audit-sprint quality gates (Yield when construct declares review: skip or audit: skip)
  • NEVER use /bug for feature work that doesn't reference an observed failure
  • NEVER implement code directly when /spiraling is invoked with a task — dispatch through the harness pipeline (/run sprint-plan, /simstim, or spiral-harness.sh)
  • NEVER create tags manually — always use semver-bump.sh for version computation

ALWAYS

  • ALWAYS route implementation through /run sprint-plan, /run sprint-N, or /bug, checking for the existing sprint plan first
  • ALWAYS create beads tasks from sprint plan before implementation (if beads available)
  • ALWAYS complete the full implement → review → audit cycle
  • ALWAYS validate bug eligibility before /bug implementation
  • ALWAYS Read a state artifact (NOTES.md, a2a/ docs, MEMORY.md, contracts/*.yaml — any existing file) before Write/Edit
  • ALWAYS use post-merge-orchestrator.sh for pipeline execution, not ad-hoc commands

Three-Zone model

Zone Path Rule
System .claude/ NEVER edit directly (use .claude/overrides/ or .loa.config.yaml)
State grimoires/, .beads/, .ck/, .run/ Read/Write
App src/, lib/, app/ Confirm writes

Conventions

  • Default PR reviewer: @deep-name (always request review).
  • Branch from main; never commit directly to the default branch.
  • Commit trailer: end commit messages with Co-Authored-By: Claude <noreply@anthropic.com>.
  • Beads-first: task lifecycle is tracked via br (beads_rust); it is the source of truth, not ad-hoc TODOs.

Context Intake (read FIRST)

Before any substantive work, consult the known-failures index, not the full log. If known_failures.surface_at_session_start is true the .claude/hooks/loa-kf-surface.sh SessionStart hook has already printed a symptom → KF table into context; otherwise run bash .claude/scripts/grimoire-index.sh and read the ## kf section of grimoires/loa/INDEX.md. Open grimoires/loa/known-failures.md at a matching ## KF-NNN: heading only for its Reading guide (full read only when authoring or repairing an entry). Recurrence count ≥ 3 means a failure class is structural; route through the upstream issue rather than retrying listed dead-ends.