# .agents/

Agent configuration for this repository. The `.agents/` layout tracks the
[agents folder convention](https://github.com/agentsfolder/spec), while skills
inside it follow the [open Agent Skills format](https://agentskills.io/specification):
each skill is a directory with `SKILL.md` frontmatter and Markdown
instructions.

SF treats this as `sf-agents-overlay/v1` until the external `.agents` spec
settles. The stable contract is:

- `.agents/manifest.yaml` is the repo-owned machine index.
- `.agents/prompts/`, `.agents/policies/`, `.agents/modes/`, `.agents/scopes/`,
  `.agents/profiles/`, and `.agents/adapters/` are optional project override
  inputs.
- `.agents/skills/<name>/SKILL.md` is the canonical skill payload.
- `.agents/skills/<name>/skill.yaml` may exist as generated or adapter metadata,
  but it is not the instruction source.
- `.agents/state/state.yaml` is local-only and ignored.
- `.sf/` remains SF runtime state; structured SF state is DB-first.

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.

This mirrors Copilot-style project customization: repository-owned agent
instructions and optional overrides live in the repo, while product-shipped
defaults live outside the repo overlay. For SF, bundled user-visible skills are
sourced from `src/resources/skills/`; hidden workflow pattern skills are sourced
from `src/resources/workflow-skills/`; bundled default prompts and policies are
sourced from `src/resources/agent-overlays/singularity-forge/`. `.agents/`
only adds project-specific overrides.

## Structure

```
.agents/
  AGENTS.md         ← this file
  manifest.yaml     ← SF overlay schema; no enabled overrides by default
  prompts/
    .gitkeep        ← project prompt overrides only
    snippets/       ← project prompt fragments only
  modes/            ← project mode OVERRIDES only (empty — SF built-ins apply)
  policies/
    .gitkeep        ← project policy overrides only
  skills/           ← optional project user skills + built-in overrides (empty by default)
  scopes/           ← path-based config overrides (empty)
  profiles/         ← named overlays e.g. "ci", "dev" (empty)
  adapters/          ← optional projection targets (absent until needed)
  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 a product workflow pattern for this repo
.agents/skills/sf-repo-orientation/SKILL.md

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

Built-in defaults (ask, build, autonomous modes; default-safe policy; bundled
prompts; bundled user skills; hidden workflow pattern skills) are provided by SF from
`src/resources/` and do not need to be listed here.
