docs(wiki): add subsystems.md and glossary.md wiki pages
Complete the standard wiki page set from sf-wiki SKILL.md: - subsystems.md: table of all subsystems with path, purpose, tests - glossary.md: project-specific terms (ADR, UOK, PDD, YOLO, wiki, etc.) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
Mikael Hugo
parent
e679478d1b
commit
b818ae2c5a
2 changed files with 190 additions and 0 deletions
119
.sf/wiki/glossary.md
Normal file
119
.sf/wiki/glossary.md
Normal file
|
|
@ -0,0 +1,119 @@
|
|||
# Glossary
|
||||
|
||||
*Generated: 2026-05-11 | Hand-editable — tracked in git*
|
||||
|
||||
Project-specific terms only. General software terms not listed.
|
||||
|
||||
---
|
||||
|
||||
## A
|
||||
|
||||
**ADR** — Architecture Decision Record. Promoted from `.sf/DECISIONS.md` to `docs/adr/`. Numbered `0000`, `0001`, … Immutable once accepted.
|
||||
|
||||
**Auto-bootstrap context** — The set of files (wiki pages, spec files, CODEBASE.md) injected as initial context for an autonomous run that has no active milestone to draw context from. Built by `auto-bootstrap-context.js` and `headless-context.ts`.
|
||||
|
||||
**Autonomous mode** — SF running the full UOK dispatch loop without human confirmation per unit. Enabled via `sf run --autonomous` or the TUI `Ctrl+Y` (YOLO flag). The controller drives planning → implementation → verification non-stop.
|
||||
|
||||
---
|
||||
|
||||
## B
|
||||
|
||||
**Blast radius** — The set of systems, users, or data that a task could affect if it produces a wrong output. One of the eight run-control fields used to determine whether a task requires human confirmation.
|
||||
|
||||
**Build mode** — The SF work mode where agent can make file changes. One of two modes (Ask/Build). Toggled via `Shift+Tab`. YOLO is a flag on top of Build, not a third mode.
|
||||
|
||||
---
|
||||
|
||||
## C
|
||||
|
||||
**CODEBASE.md** — Auto-generated file map of the repo. Gitignored. Regenerated by SF on each autonomous run start. Lives at `.sf/CODEBASE.md`.
|
||||
|
||||
**Coding agent** (`packages/coding-agent/`) — The Pi SDK package that provides tool execution, model sessions, settings, retry logic, and context management. SF wraps this to run agent units.
|
||||
|
||||
**copy-resources** — The npm script (`npm run copy-resources`) that compiles `src/resources/extensions/sf/` TypeScript + copies prompt templates into `dist/resources/`. Required after any edit to extension source files.
|
||||
|
||||
---
|
||||
|
||||
## D
|
||||
|
||||
**DB-first** — The project invariant that all structured state lives in SQLite (`node:sqlite`, `.sf/sf.db`). No file-based fallbacks for state that belongs in the DB. Never use `better-sqlite3`.
|
||||
|
||||
---
|
||||
|
||||
## E
|
||||
|
||||
**Escalation policy** — Tiers of context sources the agent should consult before acting on ambiguity. Tier 1: `.sf/` files, wiki. Tier 2: `docs/adr/`, `docs/specs/`. Tier 3: source code. Defined in `system-context.js`.
|
||||
|
||||
---
|
||||
|
||||
## F
|
||||
|
||||
**FTS5** — SQLite full-text search extension. Used for semantic memory search and session history search in `sf.db`. Queries use `WHERE search_index MATCH 'term OR synonym'` syntax.
|
||||
|
||||
---
|
||||
|
||||
## H
|
||||
|
||||
**Headless mode** — Machine-surface entry point: `sf headless`. JSON I/O. Exit codes: 0 = success, 1 = error, 10 = plan needed, 11 = blocked, 12 = budget exhausted. Not synonymous with JSON output or autonomous mode.
|
||||
|
||||
---
|
||||
|
||||
## M
|
||||
|
||||
**Milestone** — Top-level unit of planned work. Identified as `M001`, `M002`, … Stored in `sf.db`. Rendered as markdown to `.sf/milestones/M001/`. A milestone contains slices; slices contain tasks.
|
||||
|
||||
---
|
||||
|
||||
## N
|
||||
|
||||
**node:sqlite** — Node.js built-in SQLite module (Node 26+). The only allowed SQLite interface in this codebase. Never import `better-sqlite3` or any native SQLite addon.
|
||||
|
||||
---
|
||||
|
||||
## P
|
||||
|
||||
**PDD** — Purpose-Driven Development. The eight fields (intent, value, consumer, falsifier, risk, reversibility, blast-radius, cost/compliance) that define what a task is and how to run it safely.
|
||||
|
||||
**Pi SDK** — The underlying agent SDK (`packages/coding-agent`, `packages/ai`, `packages/agent-core`, `packages/tui`, etc.) that SF is built on.
|
||||
|
||||
**Promote-only rule** — Runtime agent artifacts (`.sf/milestones/`, `.sf/evals/`, locks, journals) are gitignored and never committed directly. Durable artifacts are promoted to `docs/plans/`, `docs/adr/`, `docs/specs/`.
|
||||
|
||||
**Purpose-to-Software Compiler** — The foundational product model (ADR-0000): SF captures bounded intent, translates it into PDD fields, applies run-control policy, generates milestone/slice/task contracts, writes failing tests first, implements the smallest satisfying change, then records evidence and continues.
|
||||
|
||||
---
|
||||
|
||||
## R
|
||||
|
||||
**Run-control policy** — The framework that maps confidence, risk, reversibility, blast radius, cost, compliance, and production impact to a decision on whether to proceed autonomously or ask the human. Part of PDD.
|
||||
|
||||
---
|
||||
|
||||
## S
|
||||
|
||||
**sf.db** — The canonical SQLite database at `.sf/sf.db`. Contains milestones, slices, tasks, memories, schedule entries, session logs, FTS5 search indexes. The single source of truth for all structured SF state.
|
||||
|
||||
**Slice** — A scoped, deliverable unit within a milestone. Identified as `S01`, `S02`, … Each slice maps to a coherent set of tasks. Stored in `sf.db`, rendered to `.sf/milestones/M001/S01/`.
|
||||
|
||||
**Spec-first TDD** — The project doctrine: write a failing test (the spec) before writing implementation code. `THE TEST IS THE SPEC`. See `docs/SPEC_FIRST_TDD.md`.
|
||||
|
||||
---
|
||||
|
||||
## T
|
||||
|
||||
**Task** — The smallest schedulable work unit. Identified as `T01`, `T02`, … within a slice. Stored in `sf.db`. Each task gets its own agent session context and dispatch lifecycle.
|
||||
|
||||
**Tacit knowledge** — Project-specific conventions, patterns, and institutional knowledge stored in `.sf/KNOWLEDGE.md`. Injected into system context before every SF turn.
|
||||
|
||||
---
|
||||
|
||||
## U
|
||||
|
||||
**UOK** — Unified Operation Kernel. The deterministic (non-LLM) controller that reads `sf.db`, selects the next unit, launches a fresh agent session, and records results. Lives in `src/resources/extensions/sf/auto/`.
|
||||
|
||||
---
|
||||
|
||||
## W
|
||||
|
||||
**Wiki** (`.sf/wiki/`) — Human-curated + agent-generated reference pages injected into every SF system context turn. Tracked in git (not gitignored). Hand edits persist across commits and clones. Lowercase filenames (`index.md`, `architecture.md`, etc.).
|
||||
|
||||
**YOLO** — A flag on top of Build mode that disables all safety confirmations (no git prompts, no write-gate approvals). Enabled via `Ctrl+Y` or `/mode yolo`. Not a third mode — it does not appear as a `Shift+Tab` stop.
|
||||
71
.sf/wiki/subsystems.md
Normal file
71
.sf/wiki/subsystems.md
Normal file
|
|
@ -0,0 +1,71 @@
|
|||
# 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 |
|
||||
Loading…
Add table
Reference in a new issue