# .agents/

Agent configuration for this repository following the
[AGENTS-1 spec](https://github.com/agentsfolder/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, enabled skills/policies
  prompts/
    base.md         ← injected into every agent turn (iron law, DB-first, key pointers)
    project.md      ← SF-specific context (modes, state, build commands, source layout)
    snippets/       ← reusable prompt fragments (empty — no project snippets yet)
  modes/            ← project mode OVERRIDES only (empty — SF built-ins apply)
  policies/
    default-safe.yaml ← conservative policy: confirm destructive ops, deny secrets paths
  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)
  profiles/         ← named overlays e.g. "ci", "dev" (empty)
  schemas/          ← generated JSON schemas (not committed)
  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; default-safe policy; all SF
system skills) are provided by SF and do not need to be listed here.
