53259aebf1
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
1. cooldown failover (sf-mp8w9cg9-arixq7, high) When a provider hits AUTH_COOLDOWN in unit execution, block the failing model with an expiry using the existing blockModel() API, then try a non-cooldowned provider via isProviderRequestReady. Only stops if every provider is unavailable, with an enumerated message showing which ones are down. loop.js consecutiveCooldowns is not touched here (it tracks the loop-level retry budget for provider-not-ready errors that bypass phases-unit; the cooldown path in loop.js is separate and handles errors thrown before runUnitPhase, while this fix handles cancellation returned from runUnitPhase due to provider error during session creation). 2. redundant reassess-roadmap on completed slices (sf-mp8wa4qr-xw8fjb, medium) Doctor-triggered reassess path (loop.js P4-A) now checks whether the target slice already has an ASSESSMENT file before queuing reassess-roadmap. Mirrors the guard already present in the normal dispatch path (checkNeedsReassessment). 3. empty structured fields in slice summary (sf-mp8w6s88-ckv4yr, low) Added explicit instruction in complete-slice.md prompt template directing the executor to derive key_files, key_decisions, and patterns_established from task summaries before calling complete_slice. |
||
|---|---|---|
| .. | ||
| adr | ||
| design-docs | ||
| dev | ||
| exec-plans | ||
| generated | ||
| plans | ||
| product | ||
| product-specs | ||
| records | ||
| references | ||
| specs | ||
| user-docs | ||
| DESIGN.md | ||
| ENV.md | ||
| FRONTEND.md | ||
| PLANS.md | ||
| PRODUCT_SENSE.md | ||
| QUALITY_SCORE.md | ||
| README.md | ||
| RECORDS_KEEPER.md | ||
| RELIABILITY.md | ||
| SECURITY.md | ||
| SPEC_FIRST_TDD.md | ||
| TEST-COVERAGE-PLAN.md | ||
SF Documentation
Welcome to the SF documentation. SF is a purpose-to-software compiler: it turns bounded intent into PDD contracts, researches missing context, writes failing tests or executable evidence first, implements the smallest satisfying change, and records verification. See ADR-0000 and Spec-First TDD before changing product behavior.
This index covers everything from getting started to advanced configuration, autonomous mode internals, and extending SF with the Pi SDK.
User Documentation
Guides for installing, configuring, and using SF day-to-day. Located in user-docs/.
| Guide | Description |
|---|---|
| Getting Started | Installation, first run, and basic usage |
| Autonomous Mode | How autonomous execution works — the state machine, crash recovery, and steering |
| Commands Reference | All commands, keyboard shortcuts, and CLI flags |
| Remote Questions | Discord and Slack delivery for run-control-gated questions |
| Configuration | Preferences, model selection, git settings, and token profiles |
| Provider Setup | Step-by-step setup for OpenRouter, Ollama, LM Studio, vLLM, and all supported providers |
| Custom Models | Advanced model configuration — models.json schema, compat flags, overrides |
| Token Optimization | Token profiles, context compression, complexity routing, and adaptive learning (v2.17) |
| Dynamic Model Routing | Complexity-based model selection, cost tables, escalation, and budget pressure (v2.19) |
| Captures & Triage | Fire-and-forget thought capture during autonomous mode with automated triage (v2.19) |
| Workflow Visualizer | Interactive TUI overlay for progress, dependencies, metrics, and timeline (v2.19) |
| Cost Management | Budget ceilings, cost tracking, projections, and enforcement modes |
| Git Strategy | Worktree isolation, branching model, and merge behavior |
| Parallel Orchestration | Run multiple milestones simultaneously with worker isolation and coordination |
| Working in Teams | Unique milestone IDs, .gitignore setup, and shared planning artifacts |
| Skills | Bundled skills, skill discovery, and custom skill authoring |
| Migration from v1 | Migrating .planning directories from the original SF |
| Troubleshooting | Common issues, /sf doctor (real-time visibility v2.40), /sf forensics (full debugger v2.40), and recovery procedures |
| Web Interface | Browser-based project management with sf --web (v2.41) |
| VS Code Extension | Chat participant, sidebar dashboard, and RPC integration for VS Code |
Architecture & Internals
Design documents, ADRs, and internal references. Located in dev/.
| Guide | Description |
|---|---|
| ADR-0000: Purpose-to-Software Compiler | Foundational architecture decision for SF's product contract |
| Spec-First TDD | Purpose gate, PDD fields, and test-first change method |
| Architecture Overview | System design, extension model, state-on-disk, and dispatch pipeline |
| Native Engine | Rust N-API modules for performance-critical operations |
| ADR-001: Branchless Worktree Architecture | Decision record for the v2.14 git architecture |
| ADR-003: Pipeline Simplification | Research merged into planning, mechanical completion (v2.30) |
| ADR-004: Capability-Aware Model Routing | Extend routing from tier/cost selection to task-capability matching |
| ADR-007: Model Catalog Split | Separate model metadata from routing logic for extensibility |
| Context Optimization Opportunities | Analysis of context window usage and optimization strategies |
| File System Map | Complete file system reference |
| CI/CD Pipeline | Continuous integration and deployment pipeline |
| Frontier Techniques | Advanced techniques and research |
| PRD: Branchless Worktree | Product requirements for branchless worktree architecture |
Pi SDK Documentation
Guides for the underlying Pi SDK that SF is built on. Located in dev/.
| Guide | Description |
|---|---|
| What is Pi | Core concepts — modes, agent loop, sessions, tools, providers |
| Extending Pi | Building extensions — tools, commands, UI, events, state |
| Context & Hooks | Context pipeline, hook reference, inter-extension communication |
| Pi UI / TUI | Terminal UI components, theming, keyboard input, rendering |
Research
| Guide | Description |
|---|---|
| Building Coding Agents | Research notes on agent design — decomposition, context engineering, cost/quality tradeoffs |
| Proposals | Feature proposals and workflow definitions |