Generated Artifact Policy

SF keeps operational generated artifacts out of the project root unless a human explicitly promotes them into durable project documentation.

Default Locations

.sf/ stores SF-local operational state, generated harness notes, scaffold manifests, runtime caches, locks, temporary agent files, and generated orientation caches such as .sf/repo-map/.
docs/plans/, docs/specs/, and docs/adr/ store promoted or generated human-facing exports for review and git history.
docs/generated/ stores explicitly promoted generated documentation when a project wants a generated artifact in version control.
Generated docs may change by design. Git keeps their human-facing history; SF-owned operational history belongs in .sf/SQLite when runtime replay, ledgers, memory, or drift analysis matter.
Root files such as AGENTS.md, ARCHITECTURE.md, and .siftignore are allowed only when they are part of the versioned scaffold contract.

Resource Layers

SF follows the same separation as Copilot-style agent customization:

Layer	Path	Git ownership	Purpose
Bundled SF resources	`src/resources/skills/`, `src/resources/workflow-skills/`, `src/resources/agent-overlays/`, `src/resources/extensions/sf/prompts/`, `src/resources/extensions/sf/`	tracked source	Product-shipped defaults. Change these to change SF itself. Workflow skills are hidden system patterns, not a general skill catalog.
Repo agent overlay	`.agents/`	tracked project policy	Project-owned prompts, policies, and optional user skill overrides. Same-name skills override non-locked bundled skills.
Repo instructions	`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.github/instructions/*.instructions.md`	tracked project policy	Agent-facing repo guidance. Keep short, durable, and non-runtime.
Runtime generated context	`.sf/repo-map/`, `.sf/traces/`, `.sf/backups/`, `.sf/metrics.db*`	gitignored	Local cache, observability, recovery, and orientation. Safe to delete/regenerate.
Promoted generated docs	`docs/generated/`	tracked after review	Durable generated docs that humans chose to version.

.sf/repo-map/ is not a source of truth. It is a generated context cache for agent orientation. If a repo-map page becomes valuable as documentation, promote it to docs/generated/repo-map/ or rewrite it into normal docs/.

Prompt and Instruction Layers

Prompt resources follow the same split:

Built-in prompts: src/resources/extensions/sf/prompts/ and other bundled resource directories. These ship with SF and should be edited only when changing product behavior.
Built-in repo defaults: src/resources/agent-overlays/ contains product defaults that SF ships, including default repo prompts and default policies.
Repo prompts and instructions: .agents/prompts/, root AGENTS.md, root CLAUDE.md, and compatible tool files such as .github/copilot-instructions.md. .agents/prompts/ is for repo-owned overrides only; root instruction files remain durable human-readable pointers.
Path-specific instructions: use repo instruction files when behavior should apply only to part of the tree. Keep them stable and reviewable.
Generated context: .sf/repo-map/ and other .sf/ runtime outputs are not prompt source. They may be injected as context when fresh, but they are ignored and regenerable.

Do not promote generated .sf context by copying it into prompt overlays verbatim. Summarize the durable rule, link the canonical source, and keep the overlay short enough to be loaded every run.

SF `.agents` Overlay

Until the external .agents specs settle, this repo uses sf-agents-overlay/v1:

.agents/manifest.yaml is the repo-owned machine index for optional prompt, policy, mode, adapter, and project skill overrides.
.agents/prompts/, .agents/policies/, .agents/modes/, .agents/adapters/, .agents/scopes/, and .agents/profiles/ are empty by default. Defaults live in src/resources/.
.agents/skills/<name>/SKILL.md is the canonical skill payload and follows the Agent Skills specification.
.agents/skills/ is empty by default. SF product-owned user skills live under src/resources/skills/; automatic workflow guidance lives under src/resources/workflow-skills/ as hidden system pattern skills.
SF self-learning is per repo: runtime evidence and candidate variants belong in .sf / SQLite first, reviewed repo-specific improvements are proposed as .agents/ overrides, and bundled defaults under src/resources/ change only when the improvement is product-wide.
.agents/skills/<name>/skill.yaml is optional compatibility metadata for projection tools. It may point at SKILL.md, but it must not replace it as the instruction source.
.agents/state/state.yaml is local convenience state and must remain gitignored.
.sf/ remains SF runtime state. Structured SF state stays DB-first.

Harness

Generated harness material belongs under .sf/harness/.

Top-level harness/ is not created by SF by default. If a project intentionally owns a top-level harness, SF leaves it alone unless the files still carry pending sf-doc markers proving they are old SF-generated residue.

Doctor Cleanup

/sf doctor --fix may remove root-level generated residue only when all of the following are true:

the file is under a legacy SF-generated path such as harness/specs/;
the file has an sf-doc marker;
the marker template matches the file path;
the marker state is pending;
the current body hash still matches the marker hash.

Anything edited, completed, unmarked, or project-owned is reported conservatively or left untouched.

5.7 KiB Raw Blame History