Skip to content

AGENTS.md

Latest commit

 

History

History
72 lines (55 loc) · 3.61 KB

AGENTS.md

File metadata and controls

72 lines (55 loc) · 3.61 KB
Raw

AGENTS

Use this file as the fast entry point for AI agents working in this repository.

Repo Summary

docker-library is a library of 100+ Docker Compose application packages under apps/. Each app is independent and should be runnable with docker compose up.

Start Here

Read in this order:

  1. docs/vision.md
  2. docs/architecture.md
  3. docs/code_owner.md
  4. docs/w9-env-spec.md
  5. docs/runtime-app-spec.md
  6. docs/ai-sdlc/README.md
  7. docs/upstream-spec.md
  8. .github/copilot-instructions.md

Core Rules

  • Treat each apps/<app> directory as one deployable unit.
  • Start app work with libs app-info --app <app> --json. It returns version, database lifecycle, ports, images, credentials, and tests in one call; open app files only for details it does not cover.
  • Keep changes minimal and app-local unless the task is explicitly cross-cutting.
  • Prefer official images or trusted upstream images.
  • If docker-compose.yml references ./src/..., the file must exist.
  • Follow env conventions. The canonical W9_* reference is docs/w9-env-spec.md (semantics + decision rules); use metadata/templates/new-app/.env.tmpl for layout. Read both before editing .env or docker-compose.yml.
  • Runtime/scaffold apps follow docs/runtime-app-spec.md (entrypoint hooks + optional DATABASE_URL).
  • Validate by deployment when the task changes runnable behavior. libs app-deploy auto-selects a free 9000-9999 host port on conflict and returns base_url; pass that URL to libs app-tests --base-url.
  • Quick network checks use a 2s per-attempt budget with at most 2 retries. If a target URL is unreachable locally, switch to the remote host's egress instead of extending local timeouts.
  • After a successful app update or new app with substantive changes, run libs appstore-sync --app <app> to push it to the test server's websoft9 store. Preflight the websoft9 container with a <= 10s check and skip the sync when it is absent.
  • When .secrets/remote.env exists, prefer remote-first for all runtime, deployment, debugging, and validation work; do not default to local container execution unless the user explicitly asks for local reproduction.
  • When changing skills/commands.manifest.json, command adapter templates, or skill-command mappings, run make build-ai-commands and include generated updates under .opencode/command/, .github/prompts/, and .codex/prompts/ in the same change.

i18n

  • Translatable env keys are W9_*_SET and W9_LOGIN*.
  • When a task adds or changes such keys, ensure i18n/translation.json gets the key.
  • New keys may stay ["", ""]; translations are filled by humans, not AI.
  • Do not edit downstream repos. i18n checks cover only this repo's translation.json; downstream sync workflows were removed.

Delivery Model

  • Issue is the work unit.
  • AI does research, implementation, and routine validation.
  • Owner only decides demand and final E2E result.
  • Use the quality gates in docs/ai-sdlc/05-quality-gates.md.

Main Paths

  • Apps: apps/
  • App metadata: metadata/maintenance.yaml, metadata/archive.yaml
  • Shared skills: skills/
  • Template: metadata/templates/
  • Scripts: ci/scripts/
  • Process docs: docs/ai-sdlc/
  • CI: .github/workflows/

Testing

  • Run make test; suites live in cli/tests, tests/build, tests/skills
  • Test contract: docs/test.md
  • Manual walkthrough: docs/runbook.md

When Updating Apps

  • Check upstream version and release notes first.
  • Classify the candidate using docs/ai-sdlc/02-maintenance-policy.md.
  • Update only what is required for the target version.
  • Produce a short test report using docs/ai-sdlc/06-test-report-format.md.