2bb9cdbeef
Add profile-aware scaffold system so SF does not lay down irrelevant templates in infra/ops/docs repos. ## What ships Phase 1 — data model - scaffold-versioning.js: add 'disabled' to VALID_STATES; readScaffoldManifest returns profile field; recordScaffoldApply preserves manifest.profile (fixes roundtrip bug where profile was stripped on every write). - scaffold-constants.js: PROFILES (app/library/infra/docs/minimal as Set<string>) and PROFILE_NAMES exports. Phase 2 — profile-aware drift detection - scaffold-drift.js: disabled bucket in emptyCounts, resolveActiveProfileSet integration, profile param on detectScaffoldDrift/migrateLegacyScaffold. - doc-checker.js: filter to active profile, skip disabled-state files. Phase 3 — auto-detection on first run - scaffold-profiles.js: detectRepoProfile() heuristics (nix→infra, terraform→infra, react→app, node-no-ui→library, docs-only→docs, else→app). - agentic-docs-scaffold.js: reads profile from manifest, auto-detects on first run, persists to manifest, filters SCAFFOLD_FILES to active profile. Phase 4 — migrate command - commands-scaffold-migrate.js: sf scaffold migrate --profile <name> Re-enables pending files entering the new profile; stamps state=disabled (or prunes with --prune) files leaving it; warns on editing/completed files. - commands/handlers/ops.js, commands/catalog.js: registered and tab-completed. Phase 5 — custom profiles + PREFERENCES.md frontmatter - scaffold-profiles.js: readPreferencesProfile(), loadCustomProfileSet() (~/.sf/profiles/<name>.yaml with extends/add/remove), resolveActiveProfileSet() implementing full ADR-022 §6 precedence. - All callers updated to use resolveActiveProfileSet as the single source of truth. Tests: 28 new tests in adr-022-scaffold-profiles.test.mjs — all passing. Pre-existing node:test stubs (3 files) unaffected. ADR: docs/dev/ADR-022-scaffold-profiles.md Misc: triage TODO.md dump into BACKLOG.md (phases-helpers export error T1, /todo triage typed-handler gap T1, structured triage tiers T2, sha-track markdown files T2, cross-repo triage T3). Reset TODO.md to empty template. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> |
||
|---|---|---|
| .. | ||
| adr | ||
| design-docs | ||
| dev | ||
| exec-plans | ||
| generated | ||
| plans | ||
| 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 |