singularity/singularity-forge
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
singularity-forge/.agents/AGENTS.md
Mikael Hugo ad53b792fb docs(.agents): add AGENTS.md — directory map and override pattern 
Documents every folder under .agents/, what it contains, and the
override-by-same-name pattern. Explains YOLO as a flag not a mode.

is globally ignored but the spec file under .agents/ must be tracked.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-05-11 23:48:36 +02:00

2.7 KiB
Raw Blame History

.agents/

Agent configuration for this repository following the AGENTS-1 spec.

This folder is the override and extension layer only. SF's built-in defaults (modes, skills, policies) apply automatically. Files here exist only when the project needs to override or add something.

Structure

.agents/
  AGENTS.md         ← this file
  manifest.yaml     ← specVersion, defaults (mode/policy), enabled policies + skills
  prompts/
    base.md         ← instructions injected into every agent turn
    project.md      ← project-specific context: non-negotiables, workflow, build commands
    snippets/       ← reusable prompt fragments included by modes
      style.md      ← code style rules
      principles.md ← invariants (DB-first, two modes, etc.)
      non-goals.md  ← things SF explicitly will not do
  modes/            ← project mode OVERRIDES only (add file with same name to override a default)
  policies/
    default-safe.yaml ← confirm destructive ops; deny .env/.ssh/db paths
    yolo.yaml         ← no confirmations (YOLO flag); path denies still apply
  skills/           ← project-specific skills + built-in overrides (same name = override)
    forge-autonomous-runtime/ ← explains SF autonomous loop, UOK gates, recovery paths
    forge-command-surface/    ← SF slash commands, browser command parity, headless dispatch
    nix-build/                ← build any @singularity-forge/* package via nix develop
    sf-wiki/                  ← override of built-in sf-wiki: use UPPERCASE filenames (.sf/ convention)
    smoke-test/               ← run sf-run smoke tests (--version, --help, --print)
  scopes/           ← path-based config overrides (empty — no path-specific overrides yet)
  profiles/         ← named overlays e.g. "ci", "dev" (empty — no profiles yet)
  schemas/          ← generated JSON schemas (not committed; tooling writes these)
  state/
    .gitignore      ← excludes state.yaml (per-developer convenience, never committed)

Override pattern

To override a built-in mode or skill, add a file with the same name:

# Override built-in sf-wiki skill
.agents/skills/sf-wiki/SKILL.md

# Override built-in build mode
.agents/modes/build.md

Built-in defaults (ask, build, autonomous modes; all SF system skills) are provided by SF and do not need to be listed here.

Policies

Policy When applied
default-safe Default — confirms destructive ops, denies secrets paths
yolo When YOLO flag is active (Ctrl+Y / /mode yolo) — removes confirmations, path denies still apply

YOLO is a flag on top of Build or Autonomous, not a mode. It is not a Shift+Tab stop.