SF project context

What SF is

SF is a purpose-to-software compiler: it captures bounded intent, translates it into PDD fields, researches missing context, applies run-control policy, generates milestone/slice/task contracts, writes failing tests, implements the smallest satisfying code change, and records evidence.

Foundational contract: docs/adr/0000-purpose-to-software-compiler.md.

Modes

SF has exactly two work modes: Ask and Build. Shift+Tab cycles between them. YOLO (Ctrl+Y / /mode yolo) is a flag layered on top of Build — not a third mode.

State and planning

.sf/sf.db is the canonical structured store (SQLite, node:sqlite).
Runtime planning artifacts (.sf/milestones/, .sf/evals/, locks, journals) are transient and gitignored — never committed.
Promoted artifacts go to docs/plans/, docs/adr/, docs/specs/.
Naming: milestone IDs M001…, slice IDs S01…, task IDs T01….

Build and test

npm run build          # full build
npm run build:core     # packages + tsc + resources only
npm run test:unit      # Vitest unit tests
npm run test:integration
npm run copy-resources # recompile src/resources/extensions after editing .ts files

Key source locations

Path	Purpose
`src/resources/extensions/sf/`	SF flow extension (TypeScript source)
`packages/`	Seven npm workspace packages
`web/`	Next.js browser surface
`src/headless*.ts`	`sf headless` machine-surface command
`vscode-extension/`	Editor surface

1.5 KiB Raw Blame History