# Subsystems

*Generated: 2026-05-11 | Hand-editable — tracked in git*

## Core CLI

| Subsystem | Path | Purpose | Tests |
|-----------|------|---------|-------|
| Loader / entry | `src/loader.ts` | CLI bootstrap — initialises resources, resolves extension, starts TUI or headless | `tests/smoke/` |
| Headless driver | `src/headless.ts` | Machine-surface command (`sf headless`), JSON I/O, exit codes 0/1/10/11/12 | `tests/smoke/` |
| Headless context | `src/headless-context.ts` | Bootstrap context loader for headless runs — wiki, spec files, auto-bootstrap | — |

## SF Extension (`src/resources/extensions/sf/`)

Compiled from TS → JS via `npm run copy-resources`. Edit `.ts`/`.js` source; changes only land in `dist/` after that command.

| Subsystem | Path (relative to extension) | Purpose |
|-----------|------------------------------|---------|
| UOK main loop | `auto/loop.js` | Autonomous dispatch loop — tick, gate, recovery |
| Dispatch | `auto/phases-dispatch.js` | Selects and launches the next unit (research/plan/implement/verify) |
| Phases helpers | `auto/phases-helpers.js` | Shared helpers for phase state transitions |
| Unit runner | `auto/run-unit.js` | Executes a single task plan via a fresh agent session |
| Session state | `auto/session.js` | Runtime session DB model (active unit, locks, lease) |
| Supervisor | `auto-supervisor.js` | Monitors agent runs, enforces turn/token budgets |
| Recovery | `auto-recovery.js` | Handles stuck/timeout/crash recovery for units |
| System context | `bootstrap/system-context.js` | Assembles full system prompt for every SF-managed turn |
| Auto-bootstrap context | `auto-bootstrap-context.js` | Loads context (wiki, specs, codebase) for headless auto runs with no milestones |
| DB tools | `bootstrap/db-tools.js` | SF's database query tools exposed to the agent |
| Query tools | `bootstrap/query-tools.js` | Higher-level query helpers over the DB schema |
| Memory tools | `bootstrap/memory-tools.js` | Semantic memory read/write over `sf.db` |
| Ask gate | `bootstrap/ask-gate.js` | Intercepts agent tool calls that need human confirmation |
| Write gate | `bootstrap/write-gate.js` | Intercepts destructive write operations for approval |
| Exec tools | `bootstrap/exec-tools.js` | Execution tool registration (shell commands, file ops) |
| Dynamic tools | `bootstrap/dynamic-tools.js` | Runtime tool registration based on current milestone/slice |
| Auto-prompts | `auto-prompts.js` | Loads task-execute prompt template and fills variables |
| Auto-model selection | `auto-model-selection.js` | Picks model for each unit based on capability/cost routing |
| Auto-budget | `auto-budget.js` | Tracks and enforces token and turn budgets per unit |
| Runaway guard | `auto-runaway-guard.js` | Detects infinite loop / runaway execution patterns |
| Abandon detect | `abandon-detect.js` | Detects when an agent unit has stalled or abandoned work |
| AI memory tools | `ai-memory-tools.js` | Agent-facing memory tools (store/recall facts) |
| Git runtime patterns | `git-runtime-patterns.js` | Defines which `.sf/` paths are gitignored at runtime |
| Activity log | `activity-log.js` | Appends structured activity events to `.sf/activity/` |
| Auto-dashboard | `auto-dashboard.js` | Terminal dashboard rendering during autonomous runs |
| Completion nudge | `auto-completion-nudge.js` | Prompts agent to finish when near budget limits |

## Packages (`packages/`)

| Package | Path | Purpose | Tests |
|---------|------|---------|-------|
| coding-agent | `packages/coding-agent/` | Agent core — tools (bash, grep, read…), models, sessions, settings, retry | `packages/coding-agent/tests/` |
| ai | `packages/ai/` | LLM provider adapters — Anthropic, OpenAI, Google, Moonshot, etc. | `packages/ai/tests/` |
| agent-core | `packages/agent-core/` | Shared agent abstractions, message types, streaming | — |
| tui | `packages/tui/` | Ink-based terminal UI | — |
| daemon | `packages/daemon/` | Background daemon process for persistent state | — |
| rpc-client | `packages/rpc-client/` | RPC adapter — JSON-RPC / HTTP wire protocol | — |
| native | `packages/native/` | Rust N-API bindings — grep, glob, ps, highlight, AST, diff (napi-rs) | `packages/native/tests/` |
| google-gemini-cli-provider | `packages/google-gemini-cli-provider/` | Gemini CLI Core auth provider (alternative to API key) | — |

## Key Singleton Files

| File | Role |
|------|------|
| `.sf/sf.db` | Canonical SQLite state (milestones, slices, tasks, memories, schedule, sessions) |
| `src/resources/extensions/sf/prompts/system.md` | System prompt template injected at every SF turn |
| `src/resources/extensions/sf/prompts/execute-task.md` | Per-unit task plan template |
| `.sf/PROJECT.md` | Hand-authored project identity and goals |
| `.sf/REQUIREMENTS.md` | Current requirements register |
| `.sf/DECISIONS.md` | Architecture decision log |
| `.sf/KNOWLEDGE.md` | Tacit knowledge and conventions |
| `.sf/CODEBASE.md` | Auto-generated file map (gitignored) |
| `.sf/wiki/` | Reference wiki — tracked in git, hand-editable |
