singularity-forge/.agents/AGENTS.md

.agents/

Agent configuration for this repository. The .agents/ layout tracks the agents folder convention, while skills inside it follow the open Agent Skills format: 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.