eacbbaac82
Some checks are pending
CI / detect-changes (push) Waiting to run
CI / docs-check (push) Blocked by required conditions
CI / lint (push) Blocked by required conditions
CI / build (push) Blocked by required conditions
CI / integration-tests (push) Blocked by required conditions
CI / windows-portability (push) Blocked by required conditions
CI / rtk-portability (linux, blacksmith-4vcpu-ubuntu-2404) (push) Blocked by required conditions
CI / rtk-portability (macos, macos-15) (push) Blocked by required conditions
CI / rtk-portability (windows, blacksmith-4vcpu-windows-2025) (push) Blocked by required conditions
Final settled design: sha + git ref only, no DB content snapshots at all. The mid-edit case (file observed dirty) loses the ability to reconstruct the intermediate working-tree state, but the change- detection signal is preserved and the operator can commit first if intermediate fidelity matters. Trades a corner-case fidelity loss for a much simpler schema and no DB-vs-disk content duplication. Git remains the only version store; the DB row is a pure "where I left off" pointer. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
5 KiB
5 KiB
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 |