1.7 KiB
docs/specs/
Human-readable specifications and exported contracts.
SF plans and executes from .sf, database first. .sf/sf.db is the canonical
structured store for initialized repos; .sf/*.md files are working guidance,
knowledge, generated projections, or recovery inputs.
docs/specs/ is for humans: reviewable exports, reports, public contracts, and
git-history artifacts. SF may read these files as repo evidence during analysis,
but any fact required for SF's own future operation must be captured into
.sf/DB-backed state before it is treated as operational knowledge.
Generated docs in this directory are allowed to change. That is part of their
purpose: Git keeps the human-facing history of exported contracts and reports.
SF can keep its own operational history in .sf/SQLite when it needs runtime
memory, ledgers, replay, or drift analysis.
What belongs here
- Long-lived human-readable behavior contracts, APIs, or protocols.
- Generated or promoted exports from
.sfworking state. - Reports that should be visible in git history for reviewers and future humans.
- Documents that outlive any single implementation plan but remain downstream
from
.sfwhen SF needs to use them operationally.
What does NOT belong here
- SF working plans, state, knowledge, or task control files. Keep those in
.sfand use runtime tools to mutate DB-owned records. - Architecture decisions (use
docs/adr/). - Implementation plans (use
docs/plans/). - A parallel
BASE_SPEC.mdor product-spec hierarchy for new SF work.
Naming convention
<topic>.md — e.g., promote-command-spec.md