193 lines
11 KiB
Markdown
193 lines
11 KiB
Markdown
# SF Operating Model
|
|
|
|
## Working Model Inputs
|
|
|
|
- Generator: `sf-spec-projections@1`
|
|
- Database: `.sf/sf.db` (present)
|
|
- Guidance: `.sf/PRINCIPLES.md` (present)
|
|
- Guidance: `.sf/TASTE.md` (present)
|
|
- Guidance: `.sf/ANTI-GOALS.md` (present)
|
|
- Optional knowledge: `.sf/KNOWLEDGE.md` (missing)
|
|
- Optional preferences: `.sf/PREFERENCES.md` (present)
|
|
- Source schema version: 45
|
|
- DB planning rows: milestones=1, slices=0, tasks=0
|
|
- DB spec rows: milestone_specs=1, slice_specs=0, task_specs=0
|
|
- Source roots analyzed as implementation evidence: `src/resources/extensions/sf/`, `src/headless*.ts`, `src/cli.ts`, `src/help-text.ts`, `web/`, `vscode-extension/`, `packages/`
|
|
|
|
This file is a human export for review, navigation, and git history. Generated docs are allowed to change because Git keeps the human-facing history. If SF needs operational history or future-use knowledge, store it in `.sf`/DB-backed state instead of relying on this export.
|
|
|
|
SF has one workflow engine and one database-first working model. TUI, CLI, web, editor integrations, and non-interactive automation must all drive the same flow:
|
|
|
|
```text
|
|
intent -> structured state/evidence -> UOK/policy gates -> execution -> journal/evidence -> projected status
|
|
```
|
|
|
|
The names below are separate axes. Do not use one as a synonym for another.
|
|
|
|
## Flow
|
|
|
|
The flow is the product behavior: how SF captures intent, plans work, applies policy, executes tasks, records evidence, and reports status. Flow behavior must not fork by UI surface. If a TUI run and a non-interactive run receive the same state, run control, and permission profile, they should follow the same control model.
|
|
|
|
## Surface
|
|
|
|
A surface is where a person or program drives or observes the flow.
|
|
|
|
- **TUI surface** — interactive terminal UI.
|
|
- **CLI surface** — explicit commands and single-shot prompt entrypoints.
|
|
- **Web surface** — browser UI around the same state and flow.
|
|
- **Editor surface** — IDE/editor integration, usually through an adapter.
|
|
- **Machine surface** — non-interactive runner for CI, scripts, schedulers, and parent processes.
|
|
|
|
`sf headless` is the current command name for the machine surface. It means "without the TUI"; it does not mean "JSON", "autonomous", or a separate flow.
|
|
|
|
## Protocol
|
|
|
|
A protocol is how a surface or adapter talks to SF or to another agent process.
|
|
|
|
- **RPC** — SF's current child-process control channel.
|
|
- **stdio JSON-RPC** — process transport used by existing RPC-style adapters.
|
|
- **ACP** — editor/client protocol adapter for agent/editor interoperability.
|
|
- **HTTP/RPC** — possible daemon/web integration protocol.
|
|
- **Wire** — a low-level internal message layer, if introduced, below surfaces and adapters.
|
|
|
|
Protocols are adapters around the flow. They should translate messages, not invent policy or planning semantics.
|
|
|
|
## Output Format
|
|
|
|
An output format is only the encoding of a response or event stream.
|
|
|
|
- `text` — human-readable progress and results.
|
|
- `json` — one machine-readable result object.
|
|
- `stream-json` / JSONL — event stream for parent processes and monitors.
|
|
|
|
JSON is not a surface, run control, or permission profile. It is one output format that the machine surface can emit.
|
|
|
|
## Run Control
|
|
|
|
Run control describes how far SF continues through the flow before stopping for the operator.
|
|
|
|
- **manual** — user approves each consequential step.
|
|
- **assisted** — SF proposes and executes bounded steps, with human approval for important or uncertain actions.
|
|
- **autonomous** — SF continues through the flow until policy, evidence, budget, or completion stops it.
|
|
|
|
`auto` is not a run-control mode. Use **autonomous** for continuous run control; use **assisted** for bounded human-guided progression.
|
|
|
|
> Competitor note: Copilot CLI calls continuous run control autopilot.
|
|
> SF does not use that product name. The SF term is autonomous mode,
|
|
> and it stays separate from permission profiles, surfaces, protocols,
|
|
> and output formats.
|
|
|
|
UOK kernel records carry `runControl` as a first-class lifecycle field. Workflow phases such as planning, building, verification, and finalization are separate execution stages, not run-control modes.
|
|
|
|
## Permission Profile
|
|
|
|
A permission profile describes what SF is allowed to touch when a run-control mode asks it to act.
|
|
|
|
- **restricted** — read-mostly or planning-artifact-only permissions.
|
|
- **normal** — default workspace permissions for ordinary project work.
|
|
- **trusted** — wider local permissions for a trusted operator/workspace.
|
|
- **unrestricted** — explicit danger profile; use for logs, policy records, or deliberate bypass flows, not as friendly default product language.
|
|
|
|
Run control and permission profile are independent. For example, `autonomous + restricted` can keep going with narrow permissions, while `manual + trusted` still asks before each consequential step but can perform broader approved actions.
|
|
|
|
UOK kernel records and execution-policy decisions carry `permissionProfile` as the trust posture. Permission expansion never implies autonomous continuation.
|
|
|
|
## Work Mode
|
|
|
|
A work mode describes the kind of work SF is doing. `repair` is one work mode, not a separate subsystem. It owns self-healing, stale locks, installed-runtime drift, broken state, failed gates, generated/runtime drift, and other cases where SF must repair its own ability to continue safely.
|
|
|
|
`doctor` remains a diagnostic engine. It can inspect and report problems, but switching into repair work is a `workMode` transition.
|
|
|
|
## Task And Scheduler Status
|
|
|
|
Durable task lifecycle state uses the ORCH-style status machine:
|
|
|
|
```text
|
|
todo -> running -> verifying -> reviewing -> done | blocked | paused | failed | cancelled | retrying
|
|
```
|
|
|
|
Use `todo`, not `queued`, for work that exists but has not started. `queued` belongs to scheduler state only:
|
|
|
|
```text
|
|
queued -> due -> claimed -> dispatched -> consumed | expired
|
|
```
|
|
|
|
Parallel workers must stay worktree-isolated and report heartbeat/status into `.sf` state. Their lifecycle rows use `task_status`; timed dispatch and reminder rows use `task_scheduler.status`.
|
|
|
|
## Remote Steering
|
|
|
|
Remote is a full-session steering surface. It may change `workMode`, `runControl`, `permissionProfile`, and `modelMode`; it is not only a question delivery channel.
|
|
|
|
## Future Sandbox Profile
|
|
|
|
`sandboxProfile` may become a sixth independent axis later. Keep it separate from `permissionProfile`: sandbox profile controls containment, while permission profile controls what SF may approve.
|
|
|
|
## Naming Rules
|
|
|
|
- Say **flow** for the shared planning/execution engine.
|
|
- Say **surface** for TUI, CLI, web, editor, or machine entrypoints.
|
|
- Say **protocol** for ACP, RPC, stdio JSON-RPC, HTTP, or wire messages.
|
|
- Say **output format** for `text`, `json`, and `stream-json`.
|
|
- Say **run control** for `manual`, `assisted`, and `autonomous`.
|
|
- Say **permission profile** for `restricted`, `normal`, `trusted`, and `unrestricted`.
|
|
- Say **task status** for `todo`, `running`, `verifying`, `reviewing`, `done`, `blocked`, `paused`, `failed`, `cancelled`, and `retrying`.
|
|
- Say **scheduler status** for `queued`, `due`, `claimed`, `dispatched`, `consumed`, and `expired`.
|
|
- Use **headless** only for the current `sf headless` command and implementation path. Product docs should explain it as the machine surface.
|
|
|
|
## Working State Contract
|
|
|
|
SF working state is database-first. An initialized SF repo has `.sf/sf.db`, and runtime tools use it as the canonical structured store for planning hierarchy, ordering, gates, ledgers, schedules, and validation-sensitive state.
|
|
|
|
Markdown under `.sf/` has two roles:
|
|
|
|
- working guidance and knowledge that the runtime loads, such as `PRINCIPLES.md`, `TASTE.md`, `ANTI-GOALS.md`, `KNOWLEDGE.md`, and `PREFERENCES.md`;
|
|
- human-readable projections from DB-owned records, such as rendered decisions, requirements, roadmap, plan, summary, and state files.
|
|
|
|
Markdown under `docs/specs/` is a human export for review, navigation, and git history. Generated docs can change; Git records that human-facing history. If SF needs its own operational history, it should store that in `.sf`/DB-backed state. Plans should record any surface, protocol, output-format, run-control, or permission-profile impact explicitly when a milestone changes integration behavior.
|
|
|
|
## Source Placement
|
|
|
|
SF source placement follows the same axis model. New code should extend the owning axis instead of creating parallel trees.
|
|
|
|
### Core Flow
|
|
|
|
- `src/resources/extensions/sf/` owns the SF workflow extension: planning tools, UOK/runtime state, `/next` commands, prompts, templates, doctors, schedule, and DB-backed state.
|
|
- `src/resources/extensions/` owns bundled extension packages loaded into the runtime.
|
|
- `src/resources/agents/`, `src/resources/skills/`, and `src/resources/workflows/` own bundled runtime resources, not independent product flows.
|
|
|
|
### Surfaces
|
|
|
|
- `src/cli.ts` and `src/help-text.ts` own CLI/session entrypoint behavior and command help.
|
|
- `src/headless*.ts` owns the existing `sf headless` machine-surface command path. Keep the command name; describe it as the machine surface in product language.
|
|
- `web/` owns the browser surface.
|
|
- `vscode-extension/` owns the editor surface.
|
|
- `packages/pi-tui/` owns reusable TUI primitives and terminal UI components.
|
|
|
|
### Protocols And Adapters
|
|
|
|
- `packages/rpc-client/` owns reusable RPC client protocol code.
|
|
- RPC child-process orchestration stays in the machine-surface path unless promoted into a reusable protocol package.
|
|
- ACP, stdio JSON-RPC, HTTP, and future wire layers are protocol/adapters. They should translate messages to the same SF flow, not fork planning semantics.
|
|
|
|
### Workspace Packages
|
|
|
|
- `packages/pi-agent-core/` owns reusable agent-core primitives.
|
|
- `packages/pi-ai/` owns provider/model integration.
|
|
- `packages/pi-coding-agent/` owns reusable coding-agent substrate inherited from Pi.
|
|
- `packages/daemon/` owns daemonized background service code.
|
|
- `packages/native/` and `rust-engine/` own native/Rust performance paths.
|
|
|
|
### State And Projections
|
|
|
|
- `.sf/sf.db` is the canonical structured runtime state store for initialized SF repos. Treat a missing or unreadable DB as bootstrap/recovery, not a normal alternate source of truth.
|
|
- `.sf/DECISIONS.md`, `.sf/REQUIREMENTS.md`, milestone roadmaps, and similar files are rendered working projections when database-backed tools own the data. They are useful to humans and agents but must not compete with DB rows.
|
|
- `.sf/PRINCIPLES.md`, `.sf/TASTE.md`, `.sf/ANTI-GOALS.md`, `.sf/KNOWLEDGE.md`, and `.sf/PREFERENCES.md` are repo-local working guidance files when present.
|
|
- Generated `.sf/` runtime files are evidence, projections, or import/recovery artifacts.
|
|
- Durable human-facing exports belong in `docs/specs/`, `docs/adr/`, or `docs/plans/`. They are reviewable projections and git-history artifacts, not a second planning database.
|
|
|
|
### Placement Rules
|
|
|
|
- Do not create a second implementation because a feature appears in another surface. Add an adapter to the same flow.
|
|
- Do not name output encodings as surfaces. JSON belongs to output formats.
|
|
- Do not name permission expansion as run control. `autonomous` means the loop continues; `trusted` or `unrestricted` means the permission profile widened.
|
|
- Do not route human questions because of `headless`. Questions come from run-control and permission-policy gates; the surface only determines delivery.
|