106 lines
5.7 KiB
Markdown
106 lines
5.7 KiB
Markdown
# 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.
|