Skip to content

AGENTS.md

Latest commit

 

History

History
110 lines (77 loc) · 4.45 KB

AGENTS.md

File metadata and controls

110 lines (77 loc) · 4.45 KB

AGENTS.md

Practical guidance for coding agents working in bare.

Purpose

bare is a deterministic coding-agent runtime and CLI. Favor predictable behavior, schema stability, and debuggable run artifacts over cleverness.

Read First

Before non-trivial changes, read:

  • README.md
  • docs/model-architecture.md
  • docs/adding-provider.md
  • docs/adding-model.md
  • docs/model-troubleshooting.md
  • docs/adr/0001-provider-model-architecture.md

Repository Map

  • CLI: cmd/bare/
  • Core domain/config/state: internal/domain/
  • Model/provider layer: internal/model/
  • Command execution: internal/execution/
  • Runtime persistence: internal/storage/, internal/proof/
  • Troubleshooting and architecture docs: docs/
  • Task backlog + schema: to-do.json, to-do.schema.json

Standard Commands

  • Build: go build -o bare ./cmd/bare
  • CLI smoke check: go run ./cmd/bare --help
  • Full tests: go test ./...
  • Fast model + CLI loop checks: go test ./internal/model ./cmd/bare

Review and Landing Modes

  • Review mode (PR/issue context only): read-only review, no code edits, no branch switching, no commits.
  • Landing mode (implementation requested): make scoped changes, run required tests, then summarize artifacts and outcomes.

Test Gate Policy

  • For changes in internal/model, cmd/bare, or internal/domain, run:
    • go test ./internal/model ./cmd/bare during iteration.
    • go test ./... before finalizing.
  • For documentation-only edits, tests are optional but preferred when behavior text changed.

Model and Provider Guardrails

  • Keep provider behavior deterministic and capability-driven (internal/model/models.json).
  • Do not change provider request/response contracts without tests and doc updates.
  • Preserve normalized diagnostics/error classification so retries and transcripts stay stable.
  • Z.AI defaults currently use chat_completions and endpoint family https://api.z.ai/api/paas/v4/....
  • Z.AI auth requires full token format <key_id>.<secret> in ZAI_API_KEY.
  • Be aware default model output budget is limited; large prompt responses can truncate. If you change extraction/fallback logic, add tests for partial JSON/text behavior.

Provider Change Policy

  • Any provider wire change (payload shape, endpoint resolution, auth header, response parser, error classification, retry behavior) must include:
    • targeted unit/integration tests in internal/model/*test.go (and cmd/bare/*test.go when transcript behavior changes),
    • operator-facing doc updates in README.md and/or docs/model-troubleshooting.md,
    • backward-compatibility notes when behavior differs from prior releases.

Runtime Debugging Expectations

For model/loop failures, inspect these first:

  • .bare/outputs/runs/<run_id>/iteration-*.json
  • .bare/outputs/runs/<run_id>/run.log
  • .bare/outputs/runs/<run_id>/events.jsonl
  • .bare/transcripts/runs/<run_id>/session.jsonl

Prefer concrete evidence from run artifacts over assumptions.

Task Backlog Rules

  • Keep to-do.json compliant with to-do.schema.json.
  • Required task fields: id, title, priority, status.
  • Allowed task status values: todo, doing, blocked, done.
  • When creating tasks, include actionable details, concrete steps, and affected files.

Coding and Testing Standards

  • Keep changes minimal and local; avoid broad refactors unless requested.
  • Add or update tests whenever behavior changes.
  • Run targeted tests for touched packages before finalizing.
  • Do not commit secrets, tokens, or private environment values.

Commit and Release Guardrails

  • Use Conventional Commit format: type(scope): summary.
  • Commit only task-scoped files; do not include unrelated workspace churn.
  • Do not run version bumps, tagging, release, or publish commands without explicit user approval.
  • If asked to push, first ensure required tests have passed in this workspace.

Multi-Agent Safety

  • Do not revert or reformat unrelated files.
  • Do not use destructive git commands unless explicitly requested.
  • If the tree is already dirty, scope your changes and report only files you touched.
  • Do not use git stash (including autostash), git worktree, or branch switching unless explicitly requested.
  • Never discard other agents' in-progress changes to make your task easier.

Lessons Learned Log

Maintain LESSONS_LEARNED.md for high-value discoveries:

  • Add one short entry when you resolve a non-obvious issue.
  • Format: date, symptom, root cause, fix, and prevention check.