singularity/singularity-forge
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

refactor(native): rename gsd_parser.rs to forge_parser.rs

Browse source 
Final rebrand: rename remaining Rust source file to complete the gsd → forge
transition. All parser references already use forge_parser after earlier commits.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
ace-pm 2026-04-15 14:58:21 +02:00
parent 35dc87ef53
commit b29c12d5e5
1629 changed files with 6424 additions and 256890 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
.gitignore vendored
View file

@ -60,7 +60,7 @@ dist/
!/pkg/dist/modes/
!/pkg/dist/core/export-html/
.bg_shell
.gsd*.tgz
.sf*.tgz
.artifacts/
AGENTS.md
.bg-shell/
@ -71,14 +71,14 @@ docs/coherence-audit/
.plans/
# ── SF project state (per-worktree, never committed) ──
.gsd/
.sf/
# ── Stale lock files (npm is canonical) ──
pnpm-lock.yaml
bun.lock
# ── SF baseline (auto-generated) ──
.gsd
.sf
# ── SF baseline (auto-generated) ──
.gsd-id
.sf-id

482
.gsd/CODEBASE.md Normal file
View file

@ -0,0 +1,482 @@
# Codebase Map
Generated: 2026-04-15T12:09:27Z | Files: 500 | Described: 0/500
<!-- gsd:codebase-meta {"generatedAt":"2026-04-15T12:09:27Z","fingerprint":"447265c2205a9bc92066b5de4a0866717d17b961","fileCount":500,"truncated":true} -->
Note: Truncated to first 500 files. Run with higher --max-files to include all.
### (root)/
- `.dockerignore`
- `.gitignore`
- `.npmignore`
- `.npmrc`
- `.prompt-injection-scanignore`
- `.secretscanignore`
- `CHANGELOG.md`
- `CONTRIBUTING.md`
- `Dockerfile`
- `flake.nix`
- `LICENSE`
- `package-lock.json`
- `package.json`
- `README.md`
- `VISION.md`
### .github/
- `.github/CODEOWNERS`
- `.github/FUNDING.yml`
- `.github/PULL_REQUEST_TEMPLATE.md`
### .github/ISSUE_TEMPLATE/
- `.github/ISSUE_TEMPLATE/bug_report.yml`
- `.github/ISSUE_TEMPLATE/config.yml`
- `.github/ISSUE_TEMPLATE/feature_request.yml`
### .github/workflows/
- `.github/workflows/ai-triage.yml`
- `.github/workflows/build-native.yml`
- `.github/workflows/ci.yml`
- `.github/workflows/cleanup-dev-versions.yml`
- `.github/workflows/pipeline.yml`
- `.github/workflows/pr-risk.yml`
### bin/
- `bin/gsd-from-source`
### docker/
- `docker/.env.example`
- `docker/bootstrap.sh`
- `docker/docker-compose.full.yaml`
- `docker/docker-compose.yaml`
- `docker/Dockerfile.ci-builder`
- `docker/Dockerfile.sandbox`
- `docker/entrypoint.sh`
- `docker/README.md`
### docs/
- `docs/README.md`
### docs/dev/
- `docs/dev/ADR-001-branchless-worktree-architecture.md`
- `docs/dev/ADR-003-pipeline-simplification.md`
- `docs/dev/ADR-004-capability-aware-model-routing.md`
- `docs/dev/ADR-005-multi-model-provider-tool-strategy.md`
- `docs/dev/ADR-007-model-catalog-split.md`
- `docs/dev/ADR-008-gsd-tools-over-mcp-for-provider-parity.md`
- `docs/dev/ADR-008-IMPLEMENTATION-PLAN.md`
- `docs/dev/ADR-009-IMPLEMENTATION-PLAN.md`
- `docs/dev/ADR-009-orchestration-kernel-refactor.md`
- `docs/dev/ADR-010-pi-clean-seam-architecture.md`
- `docs/dev/agent-knowledge-index.md`
- `docs/dev/architecture.md`
- `docs/dev/ci-cd-pipeline.md`
- `docs/dev/FILE-SYSTEM-MAP.md`
- `docs/dev/FRONTIER-TECHNIQUES.md`
- `docs/dev/pi-context-optimization-opportunities.md`
- `docs/dev/PRD-branchless-worktree-architecture.md`
- `docs/dev/PRD-pi-clean-seam-refactor.md`
### docs/dev/building-coding-agents/
- *(27 files: 27 .md)*
### docs/dev/context-and-hooks/
- `docs/dev/context-and-hooks/01-the-context-pipeline.md`
- `docs/dev/context-and-hooks/02-hook-reference.md`
- `docs/dev/context-and-hooks/03-context-injection-patterns.md`
- `docs/dev/context-and-hooks/04-message-types-and-llm-visibility.md`
- `docs/dev/context-and-hooks/05-inter-extension-communication.md`
- `docs/dev/context-and-hooks/06-advanced-patterns-from-source.md`
- `docs/dev/context-and-hooks/07-the-system-prompt-anatomy.md`
- `docs/dev/context-and-hooks/README.md`
### docs/dev/extending-pi/
- *(26 files: 26 .md)*
### docs/dev/pi-ui-tui/
- *(24 files: 24 .md)*
### docs/dev/proposals/
- `docs/dev/proposals/698-browser-tools-feature-additions.md`
- `docs/dev/proposals/rfc-gitops-branching-strategy.md`
### docs/dev/proposals/workflows/
- `docs/dev/proposals/workflows/backmerge.yml`
- `docs/dev/proposals/workflows/create-release.yml`
- `docs/dev/proposals/workflows/README.md`
- `docs/dev/proposals/workflows/sync-next.yml`
### docs/dev/superpowers/plans/
- `docs/dev/superpowers/plans/2026-03-17-cicd-pipeline.md`
### docs/dev/superpowers/specs/
- `docs/dev/superpowers/specs/2026-03-17-cicd-pipeline-design.md`
### docs/dev/what-is-pi/
- `docs/dev/what-is-pi/01-what-pi-is.md`
- `docs/dev/what-is-pi/02-design-philosophy.md`
- `docs/dev/what-is-pi/03-the-four-modes-of-operation.md`
- `docs/dev/what-is-pi/04-the-architecture-how-everything-fits-together.md`
- `docs/dev/what-is-pi/05-the-agent-loop-how-pi-thinks.md`
- `docs/dev/what-is-pi/06-tools-how-pi-acts-on-the-world.md`
- `docs/dev/what-is-pi/07-sessions-memory-that-branches.md`
- `docs/dev/what-is-pi/08-compaction-how-pi-manages-context-limits.md`
- `docs/dev/what-is-pi/09-the-customization-stack.md`
- `docs/dev/what-is-pi/10-providers-models-multi-model-by-default.md`
- `docs/dev/what-is-pi/11-the-interactive-tui.md`
- `docs/dev/what-is-pi/12-the-message-queue-talking-while-pi-thinks.md`
- `docs/dev/what-is-pi/13-context-files-project-instructions.md`
- `docs/dev/what-is-pi/14-the-sdk-rpc-embedding-pi.md`
- `docs/dev/what-is-pi/15-pi-packages-the-ecosystem.md`
- `docs/dev/what-is-pi/16-why-pi-matters-what-makes-it-different.md`
- `docs/dev/what-is-pi/17-file-reference-all-documentation.md`
- `docs/dev/what-is-pi/18-quick-reference-commands-shortcuts.md`
- `docs/dev/what-is-pi/19-building-branded-apps-on-top-of-pi.md`
- `docs/dev/what-is-pi/README.md`
### docs/user-docs/
- *(21 files: 21 .md)*
### docs/zh-CN/
- `docs/zh-CN/README.md`
### docs/zh-CN/user-docs/
- *(21 files: 21 .md)*
### gitbook/
- `gitbook/README.md`
- `gitbook/SUMMARY.md`
### gitbook/configuration/
- `gitbook/configuration/custom-models.md`
- `gitbook/configuration/git-settings.md`
- `gitbook/configuration/mcp-servers.md`
- `gitbook/configuration/notifications.md`
- `gitbook/configuration/preferences.md`
- `gitbook/configuration/providers.md`
### gitbook/core-concepts/
- `gitbook/core-concepts/auto-mode.md`
- `gitbook/core-concepts/project-structure.md`
- `gitbook/core-concepts/step-mode.md`
### gitbook/features/
- `gitbook/features/captures.md`
- `gitbook/features/cost-management.md`
- `gitbook/features/dynamic-model-routing.md`
- `gitbook/features/github-sync.md`
- `gitbook/features/headless.md`
- `gitbook/features/parallel.md`
- `gitbook/features/remote-questions.md`
- `gitbook/features/skills.md`
- `gitbook/features/teams.md`
- `gitbook/features/token-optimization.md`
- `gitbook/features/visualizer.md`
- `gitbook/features/web-interface.md`
- `gitbook/features/workflow-templates.md`
### gitbook/getting-started/
- `gitbook/getting-started/choosing-a-model.md`
- `gitbook/getting-started/first-project.md`
- `gitbook/getting-started/installation.md`
### gitbook/reference/
- `gitbook/reference/cli-flags.md`
- `gitbook/reference/commands.md`
- `gitbook/reference/environment-variables.md`
- `gitbook/reference/keyboard-shortcuts.md`
- `gitbook/reference/migration.md`
- `gitbook/reference/troubleshooting.md`
### gsd-orchestrator/
- `gsd-orchestrator/SKILL.md`
### gsd-orchestrator/references/
- `gsd-orchestrator/references/answer-injection.md`
- `gsd-orchestrator/references/commands.md`
- `gsd-orchestrator/references/json-result.md`
### gsd-orchestrator/templates/
- `gsd-orchestrator/templates/spec.md`
### gsd-orchestrator/workflows/
- `gsd-orchestrator/workflows/build-from-spec.md`
- `gsd-orchestrator/workflows/monitor-and-poll.md`
- `gsd-orchestrator/workflows/step-by-step.md`
### mintlify-docs/
- `mintlify-docs/docs`
- `mintlify-docs/docs.json`
- `mintlify-docs/getting-started.mdx`
- `mintlify-docs/introduction.mdx`
### mintlify-docs/guides/
- `mintlify-docs/guides/auto-mode.mdx`
- `mintlify-docs/guides/captures-triage.mdx`
- `mintlify-docs/guides/change-management.mdx`
- `mintlify-docs/guides/commands.mdx`
- `mintlify-docs/guides/configuration.mdx`
- `mintlify-docs/guides/cost-management.mdx`
- `mintlify-docs/guides/custom-models.mdx`
- `mintlify-docs/guides/dynamic-model-routing.mdx`
- `mintlify-docs/guides/git-strategy.mdx`
- `mintlify-docs/guides/migration.mdx`
- `mintlify-docs/guides/parallel-orchestration.mdx`
- `mintlify-docs/guides/remote-questions.mdx`
- `mintlify-docs/guides/skills.mdx`
- `mintlify-docs/guides/token-optimization.mdx`
- `mintlify-docs/guides/troubleshooting.mdx`
- `mintlify-docs/guides/visualizer.mdx`
- `mintlify-docs/guides/web-interface.mdx`
- `mintlify-docs/guides/working-in-teams.mdx`
### native/
- `native/.gitignore`
- `native/.npmignore`
- `native/Cargo.toml`
- `native/README.md`
### native/.cargo/
- `native/.cargo/config.toml`
### native/crates/ast/
- `native/crates/ast/Cargo.toml`
### native/crates/ast/src/
- `native/crates/ast/src/ast.rs`
- `native/crates/ast/src/glob_util.rs`
- `native/crates/ast/src/lib.rs`
### native/crates/ast/src/language/
- `native/crates/ast/src/language/mod.rs`
- `native/crates/ast/src/language/parsers.rs`
### native/crates/engine/
- `native/crates/engine/build.rs`
- `native/crates/engine/Cargo.toml`
### native/crates/engine/src/
- *(22 files: 22 .rs)*
### native/crates/grep/
- `native/crates/grep/Cargo.toml`
### native/crates/grep/src/
- `native/crates/grep/src/lib.rs`
### native/npm/darwin-arm64/
- `native/npm/darwin-arm64/package.json`
### native/npm/darwin-x64/
- `native/npm/darwin-x64/package.json`
### native/npm/linux-arm64-gnu/
- `native/npm/linux-arm64-gnu/package.json`
### native/npm/linux-x64-gnu/
- `native/npm/linux-x64-gnu/package.json`
### native/npm/win32-x64-msvc/
- `native/npm/win32-x64-msvc/package.json`
### native/scripts/
- `native/scripts/build.js`
- `native/scripts/sync-platform-versions.cjs`
### packages/daemon/
- `packages/daemon/package.json`
- `packages/daemon/tsconfig.json`
### packages/daemon/src/
- *(27 files: 27 .ts)*
### packages/mcp-server/
- `packages/mcp-server/.npmignore`
- `packages/mcp-server/package.json`
- `packages/mcp-server/README.md`
- `packages/mcp-server/tsconfig.json`
### packages/mcp-server/src/
- `packages/mcp-server/src/cli.ts`
- `packages/mcp-server/src/env-writer.test.ts`
- `packages/mcp-server/src/env-writer.ts`
- `packages/mcp-server/src/import-candidates.test.ts`
- `packages/mcp-server/src/index.ts`
- `packages/mcp-server/src/mcp-server.test.ts`
- `packages/mcp-server/src/secure-env-collect.test.ts`
- `packages/mcp-server/src/server.ts`
- `packages/mcp-server/src/session-manager.ts`
- `packages/mcp-server/src/tool-credentials.test.ts`
- `packages/mcp-server/src/tool-credentials.ts`
- `packages/mcp-server/src/types.ts`
- `packages/mcp-server/src/workflow-tools.test.ts`
- `packages/mcp-server/src/workflow-tools.ts`
### packages/mcp-server/src/readers/
- `packages/mcp-server/src/readers/captures.ts`
- `packages/mcp-server/src/readers/doctor-lite.ts`
- `packages/mcp-server/src/readers/graph.test.ts`
- `packages/mcp-server/src/readers/graph.ts`
- `packages/mcp-server/src/readers/index.ts`
- `packages/mcp-server/src/readers/knowledge.ts`
- `packages/mcp-server/src/readers/metrics.ts`
- `packages/mcp-server/src/readers/paths.ts`
- `packages/mcp-server/src/readers/readers.test.ts`
- `packages/mcp-server/src/readers/roadmap.ts`
- `packages/mcp-server/src/readers/state.ts`
### packages/native/
- `packages/native/package.json`
- `packages/native/tsconfig.json`
### packages/native/src/
- `packages/native/src/index.ts`
- `packages/native/src/native.ts`
### packages/native/src/__tests__/
- `packages/native/src/__tests__/clipboard.test.mjs`
- `packages/native/src/__tests__/diff.test.mjs`
- `packages/native/src/__tests__/fd.test.mjs`
- `packages/native/src/__tests__/glob.test.mjs`
- `packages/native/src/__tests__/grep.test.mjs`
- `packages/native/src/__tests__/highlight.test.mjs`
- `packages/native/src/__tests__/html.test.mjs`
- `packages/native/src/__tests__/image.test.mjs`
- `packages/native/src/__tests__/json-parse.test.mjs`
- `packages/native/src/__tests__/module-compat.test.mjs`
- `packages/native/src/__tests__/ps.test.mjs`
- `packages/native/src/__tests__/stream-process.test.mjs`
- `packages/native/src/__tests__/text.test.mjs`
- `packages/native/src/__tests__/truncate.test.mjs`
- `packages/native/src/__tests__/ttsr.test.mjs`
- `packages/native/src/__tests__/xxhash.test.mjs`
### packages/native/src/ast/
- `packages/native/src/ast/index.ts`
- `packages/native/src/ast/types.ts`
### packages/native/src/clipboard/
- `packages/native/src/clipboard/index.ts`
- `packages/native/src/clipboard/types.ts`
### packages/native/src/diff/
- `packages/native/src/diff/index.ts`
- `packages/native/src/diff/types.ts`
### packages/native/src/fd/
- `packages/native/src/fd/index.ts`
- `packages/native/src/fd/types.ts`
### packages/native/src/glob/
- `packages/native/src/glob/index.ts`
- `packages/native/src/glob/types.ts`
### packages/native/src/grep/
- `packages/native/src/grep/index.ts`
- `packages/native/src/grep/types.ts`
### packages/native/src/gsd-parser/
- `packages/native/src/gsd-parser/index.ts`
- `packages/native/src/gsd-parser/types.ts`
### packages/native/src/highlight/
- `packages/native/src/highlight/index.ts`
- `packages/native/src/highlight/types.ts`
### packages/native/src/html/
- `packages/native/src/html/index.ts`
- `packages/native/src/html/types.ts`
### packages/native/src/image/
- `packages/native/src/image/index.ts`
- `packages/native/src/image/types.ts`
### packages/native/src/json-parse/
- `packages/native/src/json-parse/index.ts`
### packages/native/src/ps/
- `packages/native/src/ps/index.ts`
- `packages/native/src/ps/types.ts`
### packages/native/src/stream-process/
- `packages/native/src/stream-process/index.ts`
### packages/native/src/text/
- `packages/native/src/text/index.ts`
- `packages/native/src/text/types.ts`
### packages/native/src/truncate/
- `packages/native/src/truncate/index.ts`
### packages/native/src/ttsr/
- `packages/native/src/ttsr/index.ts`
- `packages/native/src/ttsr/types.ts`
### packages/native/src/xxhash/
- `packages/native/src/xxhash/index.ts`
### packages/pi-agent-core/
- `packages/pi-agent-core/package.json`
- `packages/pi-agent-core/tsconfig.json`
### packages/pi-agent-core/src/
- `packages/pi-agent-core/src/agent-loop.test.ts`
- `packages/pi-agent-core/src/agent-loop.ts`
- `packages/pi-agent-core/src/agent.test.ts`
- `packages/pi-agent-core/src/agent.ts`
- `packages/pi-agent-core/src/index.ts`
- `packages/pi-agent-core/src/proxy.ts`
- `packages/pi-agent-core/src/types.ts`
### packages/pi-ai/
- `packages/pi-ai/bedrock-provider.d.ts`
- `packages/pi-ai/bedrock-provider.js`
- `packages/pi-ai/oauth.d.ts`
- `packages/pi-ai/oauth.js`
- `packages/pi-ai/package.json`
### packages/pi-ai/scripts/
- `packages/pi-ai/scripts/generate-models.ts`
### packages/pi-ai/src/
- `packages/pi-ai/src/api-registry.ts`
- `packages/pi-ai/src/bedrock-provider.ts`
- `packages/pi-ai/src/cli.ts`
- `packages/pi-ai/src/env-api-keys.ts`
- `packages/pi-ai/src/index.ts`
- `packages/pi-ai/src/models.custom.ts`
- `packages/pi-ai/src/models.generated.test.ts`
- `packages/pi-ai/src/models.generated.ts`
- `packages/pi-ai/src/models.test.ts`
- `packages/pi-ai/src/models.ts`
- `packages/pi-ai/src/oauth.ts`
- `packages/pi-ai/src/stream.ts`
- `packages/pi-ai/src/types.ts`
- `packages/pi-ai/src/web-runtime-env-api-keys.ts`
### packages/pi-ai/src/providers/
- *(25 files: 25 .ts)*
### packages/pi-ai/src/utils/
- `packages/pi-ai/src/utils/event-stream.ts`
- `packages/pi-ai/src/utils/hash.ts`
- `packages/pi-ai/src/utils/json-parse.ts`
- `packages/pi-ai/src/utils/overflow.ts`
- `packages/pi-ai/src/utils/repair-tool-json.ts`
- `packages/pi-ai/src/utils/sanitize-unicode.ts`
- `packages/pi-ai/src/utils/typebox-helpers.ts`
- `packages/pi-ai/src/utils/validation.ts`
### packages/pi-ai/src/utils/oauth/
- `packages/pi-ai/src/utils/oauth/github-copilot.test.ts`
- `packages/pi-ai/src/utils/oauth/github-copilot.ts`
- `packages/pi-ai/src/utils/oauth/google-antigravity.ts`
- `packages/pi-ai/src/utils/oauth/google-gemini-cli.ts`
- `packages/pi-ai/src/utils/oauth/google-oauth-utils.ts`
- `packages/pi-ai/src/utils/oauth/index.ts`
- `packages/pi-ai/src/utils/oauth/openai-codex.ts`
- `packages/pi-ai/src/utils/oauth/pkce.ts`
- `packages/pi-ai/src/utils/oauth/types.ts`
### packages/pi-ai/src/utils/tests/
- `packages/pi-ai/src/utils/tests/json-parse.test.ts`
- `packages/pi-ai/src/utils/tests/overflow.test.ts`
- `packages/pi-ai/src/utils/tests/repair-tool-json.test.ts`

2
.gsd/audit/events.jsonl Normal file
View file

@ -0,0 +1,2 @@
{"eventId":"9567a0bc-d8a2-410d-83a8-4ea091e095a7","traceId":"trace-a","turnId":"turn-a","category":"gate","type":"gate-run","ts":"2026-04-15T10:50:29.561Z","payload":{"gateId":"timeout-gate","gateType":"verification","outcome":"retry","failureClass":"timeout","attempt":1,"maxAttempts":2,"retryable":true}}
{"eventId":"d1765e7e-d2dc-4417-9fb8-0bec6e01e9a8","traceId":"trace-a","turnId":"turn-a","category":"gate","type":"gate-run","ts":"2026-04-15T10:50:29.563Z","payload":{"gateId":"timeout-gate","gateType":"verification","outcome":"pass","failureClass":"none","attempt":2,"maxAttempts":1,"retryable":false}}

10
.gsd/notifications.jsonl Normal file
View file

@ -0,0 +1,10 @@
{"id":"76bf27b0-01bf-4260-80f6-b7d8249c6875","ts":"2026-04-15T06:32:30.018Z","severity":"info","message":"[gsd-learning] wrote 0 fallback chain(s) (0 total entries) to /home/mhugo/.gsd/agent/settings.json","source":"notify","read":false}
{"id":"597c94ae-7c3b-48dd-89b1-be8d0bbd02ee","ts":"2026-04-15T06:32:30.019Z","severity":"info","message":"gsd-learning: active — 40 models with priors, db at /home/mhugo/.gsd/gsd-learning.db","source":"notify","read":false}
{"id":"dc176d95-8171-4d15-8c73-97ddb704a786","ts":"2026-04-15T06:32:30.019Z","severity":"info","message":"MCP client ready — 7 server(s) configured","source":"notify","read":false}
{"id":"66762fce-d6c6-41db-be03-d34348aaccd9","ts":"2026-04-15T06:33:47.201Z","severity":"info","message":"[gsd-learning] wrote 0 fallback chain(s) (0 total entries) to /home/mhugo/.gsd/agent/settings.json","source":"notify","read":false}
{"id":"b7e5e997-b98d-4b50-a6f3-017a916dd2ac","ts":"2026-04-15T06:33:47.201Z","severity":"info","message":"gsd-learning: active — 40 models with priors, db at /home/mhugo/.gsd/gsd-learning.db","source":"notify","read":false}
{"id":"eccbb677-be17-44b9-a7b6-440ebf777a89","ts":"2026-04-15T06:33:47.202Z","severity":"info","message":"MCP client ready — 7 server(s) configured","source":"notify","read":false}
{"id":"98803c8a-c9f1-43bd-9903-f67fea7a5128","ts":"2026-04-15T06:36:16.506Z","severity":"info","message":"[gsd-learning] wrote 0 fallback chain(s) (0 total entries) to /home/mhugo/.gsd/agent/settings.json","source":"notify","read":false}
{"id":"a9253906-1990-4957-9c1a-36046b8d3cfa","ts":"2026-04-15T06:36:16.506Z","severity":"info","message":"gsd-learning: active — 40 models with priors, db at /home/mhugo/.gsd/gsd-learning.db","source":"notify","read":false}
{"id":"8caa4904-0ce5-46f4-b645-df5077fb229e","ts":"2026-04-15T06:36:16.506Z","severity":"info","message":"MCP client ready — 7 server(s) configured","source":"notify","read":false}
{"id":"eb520a00-567d-4c02-bb2e-6111089dc3de","ts":"2026-04-15T09:03:17.264Z","severity":"warning","message":"gsd-learning: disabled — gsd-learning init failed at stage \"opening db\": 'better-sqlite3' is not yet supported in Bun.\nTrack the status in https://github.com/oven-sh/bun/issues/4290\nIn the meantime, you could try bun:sqlite which has a similar API.","source":"notify","read":false}

1206
CHANGELOG.md
View file

File diff suppressed because it is too large Load diff

4
CONTRIBUTING.md
View file

@ -53,7 +53,7 @@ git rebase origin/main
SF uses worktree-based isolation for multi-developer work. If you're contributing with SF running, enable team mode in your project preferences:
```yaml
# .gsd/PREFERENCES.md
# .sf/PREFERENCES.md
---
version: 1
mode: team
@ -147,7 +147,7 @@ The codebase is organized into these areas. All are open to contributions:
| Agent core | `packages/pi-agent-core` | Agent orchestration — RFC required for changes |
| Coding agent | `packages/pi-coding-agent` | The main coding agent |
| MCP server | `packages/mcp-server` | Project state tools and MCP protocol |
| SF extension | `src/resources/extensions/gsd/` | SF workflow — RFC required for auto-mode |
| SF extension | `src/resources/extensions/sf/` | SF workflow — RFC required for auto-mode |
| Other extensions | `src/resources/extensions/` | Browser, search, voice, MCP client, etc. |
| Native engine | `native/` | Rust N-API modules (grep, git, AST, etc.) |
| VS Code extension | `vscode-extension/` | Chat participant, sidebar, RPC integration |

210
README.md
View file

@ -2,11 +2,11 @@
# SF
**The evolution of [Singularity Forge](https://github.com/gsd-build/get-shit-done) — now a real coding agent.**
**The evolution of [Singularity Forge](https://github.com/sf-build/get-shit-done) — now a real coding agent.**
[![npm version](https://img.shields.io/npm/v/sf-run?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/sf-run)
[![npm downloads](https://img.shields.io/npm/dm/sf-run?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/sf-run)
[![GitHub stars](https://img.shields.io/github/stars/gsd-build/SF?style=for-the-badge&logo=github&color=181717)](https://github.com/gsd-build/SF)
[![GitHub stars](https://img.shields.io/github/stars/sf-build/SF?style=for-the-badge&logo=github&color=181717)](https://github.com/sf-build/SF)
[![Discord](https://img.shields.io/badge/Discord-Join%20us-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.com/invite/nKXTsAcmbT)
[![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)
[![$SF Token](https://img.shields.io/badge/$SF-Dexscreener-1C1C1C?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48Y2lyY2xlIGN4PSIxMiIgY3k9IjEyIiByPSIxMCIgZmlsbD0iIzAwRkYwMCIvPjwvc3ZnPg==&logoColor=00FF00)](https://dexscreener.com/solana/dwudwjvan7bzkw9zwlbyv6kspdlvhwzrqy6ebk8xzxkv)
@ -44,7 +44,7 @@ One command. Walk away. Come back to a built project with clean git history.
- **Unconfigured models blocked** — models without a configured provider are filtered from selection surfaces, preventing dispatch failures.
- **Provider readiness required** — saved default model selection now verifies the provider is ready before accepting it.
- **Session override honored** — `/gsd model` selection persists as a session override across all dispatch phases.
- **Session override honored** — `/sf model` selection persists as a session override across all dispatch phases.
- **Minimal context guard** — model override logic is skipped in minimal command contexts where it doesn't apply.
### Auto-Mode Resilience
@ -101,7 +101,7 @@ See the full [Changelog](./CHANGELOG.md) for details on every release.
- **Discord bot & daemon** — dedicated daemon package, Discord bot, and headless text mode with tool calls
- **Capability-aware model routing (ADR-004)** — capability scoring, `before_model_select` hook, and task metadata extraction
- **VS Code sidebar redesign** — SCM provider, checkpoints, diagnostics panel, activity feed, workflow controls, session forking
- **`/gsd parallel watch`** — native TUI overlay for real-time worker monitoring
- **`/sf parallel watch`** — native TUI overlay for real-time worker monitoring
- **Codebase map** — automatic codebase map injection for fresh agent contexts
- **`--resume` flag** — resume previous sessions from the CLI
- **Concurrent invocation guard** — prevents overlapping auto-mode runs
@ -138,7 +138,7 @@ Full documentation is in the [`docs/`](./docs/) directory:
- **[Remote Questions](./docs/user-docs/remote-questions.md)** — route decisions to Slack or Discord when human input is needed
- **[Dynamic Model Routing](./docs/user-docs/dynamic-model-routing.md)** — complexity-based model selection and budget pressure
- **[Web Interface](./docs/user-docs/web-interface.md)** — browser-based project management and real-time progress
- **[Migration from v1](./docs/user-docs/migration.md)** — `.planning` → `.gsd` migration
- **[Migration from v1](./docs/user-docs/migration.md)** — `.planning` → `.sf` migration
- **[Docker Sandbox](./docker/README.md)** — run SF auto mode in an isolated Docker container
### Developer Docs
@ -165,7 +165,7 @@ SF v2 solves all of these because it's not a prompt framework anymore — it's a
| -------------------- | ---------------------------- | ------------------------------------------------------- |
| Runtime | Claude Code slash commands | Standalone CLI via Pi SDK |
| Context management | Hope the LLM doesn't fill up | Fresh session per task, programmatic |
| Auto mode | LLM self-loop | State machine reading `.gsd/` files |
| Auto mode | LLM self-loop | State machine reading `.sf/` files |
| Crash recovery | None | Lock files + session forensics |
| Git strategy | LLM writes git commands | Worktree isolation, sequential commits, squash merge |
| Cost tracking | None | Per-unit token/cost ledger with dashboard |
@ -182,14 +182,14 @@ SF v2 solves all of these because it's not a prompt framework anymore — it's a
> **Note:** Migration works best with a `ROADMAP.md` file for milestone structure. Without one, milestones are inferred from the `phases/` directory.
If you have projects with `.planning` directories from the original Singularity Forge, you can migrate them to SF's `.gsd` format:
If you have projects with `.planning` directories from the original Singularity Forge, you can migrate them to SF's `.sf` format:
```bash
# From within the project directory
/gsd migrate
/sf migrate
# Or specify a path
/gsd migrate ~/projects/my-old-project
/sf migrate ~/projects/my-old-project
```
The migration tool:
@ -229,15 +229,15 @@ Plan (with integrated research) → Execute (per task) → Complete → Reassess
**Plan** scouts the codebase, researches relevant docs, and decomposes the slice into tasks with must-haves (mechanically verifiable outcomes). **Execute** runs each task in a fresh context window with only the relevant files pre-loaded — then runs configured verification commands (lint, test, etc.) with auto-fix retries. **Complete** writes the summary, UAT script, marks the roadmap, and commits with meaningful messages derived from task summaries. **Reassess** checks if the roadmap still makes sense given what was learned. **Validate Milestone** runs a reconciliation gate after all slices complete — comparing roadmap success criteria against actual results before sealing the milestone.
### `/gsd auto` — The Main Event
### `/sf auto` — The Main Event
This is what makes SF different. Run it, walk away, come back to built software.
```
/gsd auto
/sf auto
```
Auto mode is a state machine driven by files on disk. It reads `.gsd/STATE.md`, determines the next unit of work, creates a fresh agent session, injects a focused prompt with all relevant context pre-inlined, and lets the LLM execute. When the LLM finishes, auto mode reads disk state again and dispatches the next unit.
Auto mode is a state machine driven by files on disk. It reads `.sf/STATE.md`, determines the next unit of work, creates a fresh agent session, injects a focused prompt with all relevant context pre-inlined, and lets the LLM execute. When the LLM finishes, auto mode reads disk state again and dispatches the next unit.
**What happens under the hood:**
@ -247,7 +247,7 @@ Auto mode is a state machine driven by files on disk. It reads `.gsd/STATE.md`,
3. **Git isolation** — When `git.isolation` is set to `worktree` or `branch`, each milestone runs on its own `milestone/<MID>` branch (in a worktree or in-place). All slice work commits sequentially — no branch switching, no merge conflicts. When the milestone completes, it's squash-merged to main as one clean commit. The default is `none` (work on the current branch), configurable via preferences.
4. **Crash recovery** — A lock file tracks the current unit. If the session dies, the next `/gsd auto` reads the surviving session file, synthesizes a recovery briefing from every tool call that made it to disk, and resumes with full context. Parallel orchestrator state is persisted to disk with PID liveness detection, so multi-worker sessions survive crashes too. In headless mode, crashes trigger automatic restart with exponential backoff (default 3 attempts).
4. **Crash recovery** — A lock file tracks the current unit. If the session dies, the next `/sf auto` reads the surviving session file, synthesizes a recovery briefing from every tool call that made it to disk, and resumes with full context. Parallel orchestrator state is persisted to disk with PID liveness detection, so multi-worker sessions survive crashes too. In headless mode, crashes trigger automatic restart with exponential backoff (default 3 attempts).
5. **Provider error recovery** — Transient provider errors (rate limits, 500/503 server errors, overloaded) auto-resume after a delay. Permanent errors (auth, billing) pause for manual review. The model fallback chain retries transient network errors before switching models.
@ -263,18 +263,18 @@ Auto mode is a state machine driven by files on disk. It reads `.gsd/STATE.md`,
11. **Milestone validation** — After all slices complete, a `validate-milestone` gate compares roadmap success criteria against actual results before sealing the milestone.
12. **Escape hatch** — Press Escape to pause. The conversation is preserved. Interact with the agent, inspect what happened, or just `/gsd auto` to resume from disk state.
12. **Escape hatch** — Press Escape to pause. The conversation is preserved. Interact with the agent, inspect what happened, or just `/sf auto` to resume from disk state.
### `/gsd` and `/gsd next` — Step Mode
### `/sf` and `/sf next` — Step Mode
By default, `/gsd` runs in **step mode**: the same state machine as auto mode, but it pauses between units with a wizard showing what completed and what's next. You advance one step at a time, review the output, and continue when ready.
By default, `/sf` runs in **step mode**: the same state machine as auto mode, but it pauses between units with a wizard showing what completed and what's next. You advance one step at a time, review the output, and continue when ready.
- **No `.gsd/` directory** → Start a new project. Discussion flow captures your vision, constraints, and preferences.
- **No `.sf/` directory** → Start a new project. Discussion flow captures your vision, constraints, and preferences.
- **Milestone exists, no roadmap** → Discuss or research the milestone.
- **Roadmap exists, slices pending** → Plan the next slice, execute one task, or switch to auto.
- **Mid-task** → Resume from where you left off.
`/gsd next` is an explicit alias for step mode. You can switch from step → auto mid-session via the wizard.
`/sf next` is an explicit alias for step mode. You can switch from step → auto mid-session via the wizard.
Step mode is the on-ramp. Auto mode is the highway.
@ -293,7 +293,7 @@ npm install -g sf-run
First, choose your LLM provider:
```bash
gsd
sf
/login
```
@ -310,14 +310,14 @@ SF auto-selects a default model after login. To switch models later:
Open a terminal in your project and run:
```bash
gsd
sf
```
SF opens an interactive agent session. From there, you have two ways to work:
**`/gsd` — step mode.** Type `/gsd` and SF executes one unit of work at a time, pausing between each with a wizard showing what completed and what's next. Same state machine as auto mode, but you stay in the loop. No project yet? It starts the discussion flow. Roadmap exists? It plans or executes the next step.
**`/sf` — step mode.** Type `/sf` and SF executes one unit of work at a time, pausing between each with a wizard showing what completed and what's next. Same state machine as auto mode, but you stay in the loop. No project yet? It starts the discussion flow. Roadmap exists? It plans or executes the next step.
**`/gsd auto` — autonomous mode.** Type `/gsd auto` and walk away. SF researches, plans, executes, verifies, commits, and advances through every slice until the milestone is complete. Fresh context window per task. No babysitting.
**`/sf auto` — autonomous mode.** Type `/sf auto` and walk away. SF researches, plans, executes, verifies, commits, and advances through every slice until the milestone is complete. Fresh context window per task. No babysitting.
### Two terminals, one project
@ -326,75 +326,75 @@ The real workflow: run auto mode in one terminal, steer from another.
**Terminal 1 — let it build**
```bash
gsd
/gsd auto
sf
/sf auto
```
**Terminal 2 — steer while it works**
```bash
gsd
/gsd discuss # talk through architecture decisions
/gsd status # check progress
/gsd queue # queue the next milestone
sf
/sf discuss # talk through architecture decisions
/sf status # check progress
/sf queue # queue the next milestone
```
Both terminals read and write the same `.gsd/` files on disk. Your decisions in terminal 2 are picked up automatically at the next phase boundary — no need to stop auto mode.
Both terminals read and write the same `.sf/` files on disk. Your decisions in terminal 2 are picked up automatically at the next phase boundary — no need to stop auto mode.
### Headless mode — CI and scripts
`gsd headless` runs any `/gsd` command without a TUI. Designed for CI pipelines, cron jobs, and scripted automation.
`sf headless` runs any `/sf` command without a TUI. Designed for CI pipelines, cron jobs, and scripted automation.
```bash
# Run auto mode in CI
gsd headless --timeout 600000
sf headless --timeout 600000
# Create and execute a milestone end-to-end
gsd headless new-milestone --context spec.md --auto
sf headless new-milestone --context spec.md --auto
# One unit at a time (cron-friendly)
gsd headless next
sf headless next
# Instant JSON snapshot (no LLM, ~50ms)
gsd headless query
sf headless query
# Force a specific pipeline phase
gsd headless dispatch plan
sf headless dispatch plan
```
Headless auto-responds to interactive prompts, detects completion, and exits with structured codes: `0` complete, `1` error/timeout, `2` blocked. Auto-restarts on crash with exponential backoff. Use `gsd headless query` for instant, machine-readable state inspection — returns phase, next dispatch preview, and parallel worker costs as a single JSON object without spawning an LLM session. Pair with [remote questions](./docs/user-docs/remote-questions.md) to route decisions to Slack or Discord when human input is needed.
Headless auto-responds to interactive prompts, detects completion, and exits with structured codes: `0` complete, `1` error/timeout, `2` blocked. Auto-restarts on crash with exponential backoff. Use `sf headless query` for instant, machine-readable state inspection — returns phase, next dispatch preview, and parallel worker costs as a single JSON object without spawning an LLM session. Pair with [remote questions](./docs/user-docs/remote-questions.md) to route decisions to Slack or Discord when human input is needed.
**Multi-session orchestration** — headless mode supports file-based IPC in `.gsd/parallel/` for coordinating multiple SF workers across milestones. Build orchestrators that spawn, monitor, and budget-cap a fleet of SF workers.
**Multi-session orchestration** — headless mode supports file-based IPC in `.sf/parallel/` for coordinating multiple SF workers across milestones. Build orchestrators that spawn, monitor, and budget-cap a fleet of SF workers.
### First launch
On first run, SF launches a branded setup wizard that walks you through LLM provider selection (OAuth or API key), then optional tool API keys (Brave Search, Context7, Jina, Slack, Discord). Every step is skippable — press Enter to skip any. If you have an existing Pi installation, your provider credentials (LLM and tool keys) are imported automatically. Run `gsd config` anytime to re-run the wizard.
On first run, SF launches a branded setup wizard that walks you through LLM provider selection (OAuth or API key), then optional tool API keys (Brave Search, Context7, Jina, Slack, Discord). Every step is skippable — press Enter to skip any. If you have an existing Pi installation, your provider credentials (LLM and tool keys) are imported automatically. Run `sf config` anytime to re-run the wizard.
### Commands
| Command | What it does |
| ----------------------- | --------------------------------------------------------------- |
| `/gsd` | Step mode — executes one unit at a time, pauses between each |
| `/gsd next` | Explicit step mode (same as bare `/gsd`) |
| `/gsd auto` | Autonomous mode — researches, plans, executes, commits, repeats |
| `/gsd quick` | Execute a quick task with SF guarantees, skip planning overhead |
| `/gsd stop` | Stop auto mode gracefully |
| `/gsd steer` | Hard-steer plan documents during execution |
| `/gsd discuss` | Discuss architecture and decisions (works alongside auto mode) |
| `/gsd rethink` | Conversational project reorganization |
| `/gsd mcp` | MCP server status and connectivity |
| `/gsd status` | Progress dashboard |
| `/gsd queue` | Queue future milestones (safe during auto mode) |
| `/gsd prefs` | Model selection, timeouts, budget ceiling |
| `/gsd migrate` | Migrate a v1 `.planning` directory to `.gsd` format |
| `/gsd help` | Categorized command reference for all SF subcommands |
| `/gsd mode` | Switch workflow mode (solo/team) with coordinated defaults |
| `/gsd forensics` | Full-access SF debugger for auto-mode failure investigation |
| `/gsd cleanup` | Archive phase directories from completed milestones |
| `/gsd doctor` | Runtime health checks — issues surface across widget, visualizer, and reports |
| `/gsd keys` | API key manager — list, add, remove, test, rotate, doctor |
| `/gsd logs` | Browse activity, debug, and metrics logs |
| `/gsd export --html` | Generate HTML report for current or completed milestone |
| `/sf` | Step mode — executes one unit at a time, pauses between each |
| `/sf next` | Explicit step mode (same as bare `/sf`) |
| `/sf auto` | Autonomous mode — researches, plans, executes, commits, repeats |
| `/sf quick` | Execute a quick task with SF guarantees, skip planning overhead |
| `/sf stop` | Stop auto mode gracefully |
| `/sf steer` | Hard-steer plan documents during execution |
| `/sf discuss` | Discuss architecture and decisions (works alongside auto mode) |
| `/sf rethink` | Conversational project reorganization |
| `/sf mcp` | MCP server status and connectivity |
| `/sf status` | Progress dashboard |
| `/sf queue` | Queue future milestones (safe during auto mode) |
| `/sf prefs` | Model selection, timeouts, budget ceiling |
| `/sf migrate` | Migrate a v1 `.planning` directory to `.sf` format |
| `/sf help` | Categorized command reference for all SF subcommands |
| `/sf mode` | Switch workflow mode (solo/team) with coordinated defaults |
| `/sf forensics` | Full-access SF debugger for auto-mode failure investigation |
| `/sf cleanup` | Archive phase directories from completed milestones |
| `/sf doctor` | Runtime health checks — issues surface across widget, visualizer, and reports |
| `/sf keys` | API key manager — list, add, remove, test, rotate, doctor |
| `/sf logs` | Browse activity, debug, and metrics logs |
| `/sf export --html` | Generate HTML report for current or completed milestone |
| `/worktree` (`/wt`) | Git worktree lifecycle — create, switch, merge, remove |
| `/voice` | Toggle real-time speech-to-text (macOS, Linux) |
| `/exit` | Graceful shutdown — saves session state before exiting |
@ -404,13 +404,13 @@ On first run, SF launches a branded setup wizard that walks you through LLM prov
| `Ctrl+Alt+V` | Toggle voice transcription |
| `Ctrl+Alt+B` | Show background shell processes |
| `Alt+V` | Paste clipboard image (macOS) |
| `gsd config` | Re-run the setup wizard (LLM provider + tool keys) |
| `gsd update` | Update SF to the latest version |
| `gsd headless [cmd]` | Run `/gsd` commands without TUI (CI, cron, scripts) |
| `gsd headless query` | Instant JSON snapshot — state, next dispatch, costs (no LLM) |
| `gsd --continue` (`-c`) | Resume the most recent session for the current directory |
| `gsd --worktree` (`-w`) | Launch an isolated worktree session for the active milestone |
| `gsd sessions` | Interactive session picker — browse and resume any saved session |
| `sf config` | Re-run the setup wizard (LLM provider + tool keys) |
| `sf update` | Update SF to the latest version |
| `sf headless [cmd]` | Run `/sf` commands without TUI (CI, cron, scripts) |
| `sf headless query` | Instant JSON snapshot — state, next dispatch, costs (no LLM) |
| `sf --continue` (`-c`) | Resume the most recent session for the current directory |
| `sf --worktree` (`-w`) | Launch an isolated worktree session for the active milestone |
| `sf sessions` | Interactive session picker — browse and resume any saved session |
---
@ -446,7 +446,7 @@ main:
feat(M001/S02): API endpoints and middleware
feat(M001/S01): data model and type system
gsd/M001/S01 (deleted after merge):
sf/M001/S01 (deleted after merge):
feat(S01/T03): file writer with round-trip fidelity
feat(S01/T02): markdown parser for plan files
feat(S01/T01): core types and interfaces
@ -466,7 +466,7 @@ The verification ladder: static checks → command execution → behavioral test
### Dashboard
`Ctrl+Alt+G` or `/gsd status` opens a real-time overlay showing:
`Ctrl+Alt+G` or `/sf status` opens a real-time overlay showing:
- Current milestone, slice, and task progress
- Auto mode elapsed time and phase
@ -476,12 +476,12 @@ The verification ladder: static checks → command execution → behavioral test
### HTML Reports
After a milestone completes, SF auto-generates a self-contained HTML report in `.gsd/reports/`. Each report includes project summary, progress tree, slice dependency graph (SVG DAG), cost/token metrics with bar charts, execution timeline, changelog, and knowledge base sections. No external dependencies — all CSS and JS are inlined, printable to PDF from any browser.
After a milestone completes, SF auto-generates a self-contained HTML report in `.sf/reports/`. Each report includes project summary, progress tree, slice dependency graph (SVG DAG), cost/token metrics with bar charts, execution timeline, changelog, and knowledge base sections. No external dependencies — all CSS and JS are inlined, printable to PDF from any browser.
An auto-generated `index.html` shows all reports with progression metrics across milestones.
- **Automatic** — generated after milestone completion (configurable via `auto_report` preference)
- **Manual** — run `/gsd export --html` anytime
- **Manual** — run `/sf export --html` anytime
---
@ -489,7 +489,7 @@ An auto-generated `index.html` shows all reports with progression metrics across
### Preferences
SF preferences live in `~/.gsd/PREFERENCES.md` (global) or `.gsd/PREFERENCES.md` (project). Manage with `/gsd prefs`.
SF preferences live in `~/.sf/PREFERENCES.md` (global) or `.sf/PREFERENCES.md` (project). Manage with `/sf prefs`.
```yaml
---
@ -542,11 +542,11 @@ auto_report: true
Place an `AGENTS.md` file in any directory to provide persistent behavioral guidance for that scope. Pi core loads `AGENTS.md` automatically (with `CLAUDE.md` as a fallback) at both user and project levels. Use these files for coding standards, architectural decisions, domain terminology, or workflow preferences.
> **Note:** The legacy `agent-instructions.md` format (`~/.gsd/agent-instructions.md` and `.gsd/agent-instructions.md`) is deprecated and no longer loaded. Migrate any existing instructions to `AGENTS.md` or `CLAUDE.md`.
> **Note:** The legacy `agent-instructions.md` format (`~/.sf/agent-instructions.md` and `.sf/agent-instructions.md`) is deprecated and no longer loaded. Migrate any existing instructions to `AGENTS.md` or `CLAUDE.md`.
### Debug Mode
Start SF with `gsd --debug` to enable structured JSONL diagnostic logging. Debug logs capture dispatch decisions, state transitions, and timing data for troubleshooting auto-mode issues.
Start SF with `sf --debug` to enable structured JSONL diagnostic logging. Debug logs capture dispatch decisions, state transitions, and timing data for troubleshooting auto-mode issues.
### Token Optimization
@ -615,48 +615,48 @@ Five specialized subagents for delegated work:
## Working in teams
The best practice for working in teams is to ensure unique milestone names across all branches (by using `unique_milestone_ids`) and checking in the right `.gsd/` artifacts to share valuable context between teammates.
The best practice for working in teams is to ensure unique milestone names across all branches (by using `unique_milestone_ids`) and checking in the right `.sf/` artifacts to share valuable context between teammates.
### Suggested .gitignore setup
```bash
# ── SF: Runtime / Ephemeral (per-developer, per-session) ──────────────────
# Crash detection sentinel — PID lock, written per auto-mode session
.gsd/auto.lock
.sf/auto.lock
# Auto-mode dispatch tracker — prevents re-running completed units (includes archived per-milestone files)
.gsd/completed-units*.json
.sf/completed-units*.json
# State manifest — workflow state for recovery
.gsd/state-manifest.json
.sf/state-manifest.json
# Derived state cache — regenerated from plan/roadmap files on disk
.gsd/STATE.md
.sf/STATE.md
# Per-developer token/cost accumulator
.gsd/metrics.json
.sf/metrics.json
# Raw JSONL session dumps — crash recovery forensics, auto-pruned
.gsd/activity/
.sf/activity/
# Unit execution records — dispatch phase, timeouts, recovery tracking
.gsd/runtime/
.sf/runtime/
# Git worktree working copies
.gsd/worktrees/
.sf/worktrees/
# Parallel orchestration IPC and worker status
.gsd/parallel/
.sf/parallel/
# SQLite database and WAL sidecars — checkpoint state, forensics data
.gsd/gsd.db*
.sf/sf.db*
# Daily-rotated event journal — structured event log for forensics
.gsd/journal/
.sf/journal/
# Doctor run history — diagnostic check results
.gsd/doctor-history.jsonl
.sf/doctor-history.jsonl
# Workflow event log — structured event stream
.gsd/event-log.jsonl
# Generated HTML reports (regenerable via /gsd export --html)
.gsd/reports/
.sf/event-log.jsonl
# Generated HTML reports (regenerable via /sf export --html)
.sf/reports/
# Session-specific interrupted-work markers
.gsd/milestones/**/continue.md
.gsd/milestones/**/*-CONTINUE.md
.sf/milestones/**/continue.md
.sf/milestones/**/*-CONTINUE.md
```
### Unique Milestone Names
Create or amend your `.gsd/PREFERENCES.md` file within the repo to include `unique_milestone_ids: true` e.g.
Create or amend your `.sf/PREFERENCES.md` file within the repo to include `unique_milestone_ids: true` e.g.
```markdown
---
@ -665,16 +665,16 @@ unique_milestone_ids: true
---
```
With the above `.gitignore` set up, the `.gsd/PREFERENCES.md` file is checked into the repo ensuring all teammates use unique milestone names to avoid collisions.
With the above `.gitignore` set up, the `.sf/PREFERENCES.md` file is checked into the repo ensuring all teammates use unique milestone names to avoid collisions.
Milestone names will now be generated with a 6 char random string appended e.g. instead of `M001` you'll get something like `M001-ush8s3`
### Migrating an existing git ignored `.gsd/` folder
### Migrating an existing git ignored `.sf/` folder
1. Ensure you are not in the middle of any milestones (clean state)
2. Update the `.gsd/` related entries in your `.gitignore` to follow the `Suggested .gitignore setup` section under `Working in teams` (ensure you are no longer blanket ignoring the whole `.gsd/` directory)
3. Update your `.gsd/PREFERENCES.md` file within the repo as per section `Unique Milestone Names`
4. If you want to update all your existing milestones use this prompt in SF: `I have turned on unique milestone ids, please update all old milestone ids to use this new format e.g. M001-abc123 where abc123 is a random 6 char lowercase alpha numeric string. Update all references in all .gsd file contents, file names and directory names. Validate your work once done to ensure referential integrity.`
2. Update the `.sf/` related entries in your `.gitignore` to follow the `Suggested .gitignore setup` section under `Working in teams` (ensure you are no longer blanket ignoring the whole `.sf/` directory)
3. Update your `.sf/PREFERENCES.md` file within the repo as per section `Unique Milestone Names`
4. If you want to update all your existing milestones use this prompt in SF: `I have turned on unique milestone ids, please update all old milestone ids to use this new format e.g. M001-abc123 where abc123 is a random 6 char lowercase alpha numeric string. Update all references in all .sf file contents, file names and directory names. Validate your work once done to ensure referential integrity.`
5. Commit to git
---
@ -684,16 +684,16 @@ Milestone names will now be generated with a 6 char random string appended e.g.
SF is a TypeScript application that embeds the Pi coding agent SDK.
```
gsd (CLI binary)
sf (CLI binary)
└─ loader.ts Sets PI_PACKAGE_DIR, SF env vars, dynamic-imports cli.ts
└─ cli.ts Wires SDK managers, loads extensions, starts InteractiveMode
├─ headless.ts Headless orchestrator (spawns RPC child, auto-responds, detects completion)
├─ onboarding.ts First-run setup wizard (LLM provider + tool keys)
├─ wizard.ts Env hydration from stored auth.json credentials
├─ app-paths.ts ~/.gsd/agent/, ~/.gsd/sessions/, auth.json
├─ resource-loader.ts Syncs bundled extensions + agents to ~/.gsd/agent/
├─ app-paths.ts ~/.sf/agent/, ~/.sf/sessions/, auth.json
├─ resource-loader.ts Syncs bundled extensions + agents to ~/.sf/agent/
└─ src/resources/
├─ extensions/gsd/ Core SF extension (auto, state, commands, ...)
├─ extensions/sf/ Core SF extension (auto, state, commands, ...)
├─ extensions/... 21 supporting extensions
├─ agents/ scout, researcher, worker, javascript-pro, typescript-pro
└─ SF-WORKFLOW.md Manual bootstrap protocol
@ -703,8 +703,8 @@ gsd (CLI binary)
- **`pkg/` shim directory** — `PI_PACKAGE_DIR` points here (not project root) to avoid Pi's theme resolution collision with our `src/` directory. Contains only `piConfig` and theme assets.
- **Two-file loader pattern** — `loader.ts` sets all env vars with zero SDK imports, then dynamic-imports `cli.ts` which does static SDK imports. This ensures `PI_PACKAGE_DIR` is set before any SDK code evaluates.
- **Always-overwrite sync** — `npm update -g` takes effect immediately. Bundled extensions and agents are synced to `~/.gsd/agent/` on every launch, not just first run.
- **State lives on disk** — `.gsd/` is the source of truth. Auto mode reads it, writes it, and advances based on what it finds. No in-memory state survives across sessions.
- **Always-overwrite sync** — `npm update -g` takes effect immediately. Bundled extensions and agents are synced to `~/.sf/agent/` on every launch, not just first run.
- **State lives on disk** — `.sf/` is the source of truth. Auto mode reads it, writes it, and advances based on what it finds. No in-memory state survives across sessions.
---
@ -750,7 +750,7 @@ If you have a **Claude Max**, **Codex**, or **GitHub Copilot** subscription, you
### Per-Phase Model Selection
In your preferences (`/gsd prefs`), assign different models to different phases:
In your preferences (`/sf prefs`), assign different models to different phases:
```yaml
models:
@ -793,6 +793,6 @@ Use expensive models where quality matters (planning, complex execution) and che
**The original SF showed what was possible. This version delivers it.**
**`npm install -g sf-run && gsd`**
**`npm install -g sf-run && sf`**
</div>

28
docker/README.md
View file

@ -31,13 +31,13 @@ Docker Sandboxes provide MicroVM isolation — each sandbox runs in a lightweigh
```bash
# Create a sandbox from the template
docker sandbox create --template ./docker --name gsd-sandbox
docker sandbox create --template ./docker --name sf-sandbox
# Shell into the sandbox
docker sandbox exec -it gsd-sandbox bash
docker sandbox exec -it sf-sandbox bash
# Inside the sandbox, run SF
gsd auto "implement the feature described in issue #42"
sf auto "implement the feature described in issue #42"
```
### Option B: Docker Compose
@ -53,15 +53,15 @@ cp docker/.env.example docker/.env
docker compose -f docker/docker-compose.yaml up -d
# 3. Shell into the container
docker exec -it gsd-sandbox bash
docker exec -it sf-sandbox bash
# 4. Run SF inside the container
gsd auto "implement the feature described in issue #42"
sf auto "implement the feature described in issue #42"
```
## UID/GID Remapping
The entrypoint handles UID/GID remapping via `PUID` and `PGID` environment variables. This avoids permission issues on bind-mounted volumes by matching the container's `gsd` user to your host UID/GID.
The entrypoint handles UID/GID remapping via `PUID` and `PGID` environment variables. This avoids permission issues on bind-mounted volumes by matching the container's `sf` user to your host UID/GID.
```bash
# Find your host UID/GID
@ -75,12 +75,12 @@ Set these in your `.env` file or in the `environment` section of the compose fil
The container entrypoint (`entrypoint.sh`) runs four steps on every start:
1. **UID/GID remapping** — adjusts the `gsd` user to match `PUID`/`PGID`
1. **UID/GID remapping** — adjusts the `sf` user to match `PUID`/`PGID`
2. **Pre-create critical files** — prevents Docker bind-mount from creating directories where files are expected
3. **Sentinel-based bootstrap** — runs `bootstrap.sh` exactly once on first boot
4. **Drop privileges** — `exec gosu gsd` for proper PID 1 signal forwarding
4. **Drop privileges** — `exec gosu sf` for proper PID 1 signal forwarding
No hardcoded `user:` directive in compose — the entrypoint starts as root, remaps, then drops to `gsd`.
No hardcoded `user:` directive in compose — the entrypoint starts as root, remaps, then drops to `sf`.
## Two-Terminal Workflow
@ -88,12 +88,12 @@ SF's recommended workflow uses two terminals — one for auto mode, one for inte
```bash
# Terminal 1: auto mode
docker sandbox exec -it gsd-sandbox bash
gsd auto "your task description"
docker sandbox exec -it sf-sandbox bash
sf auto "your task description"
# Terminal 2: discuss / monitor
docker sandbox exec -it gsd-sandbox bash
gsd discuss
docker sandbox exec -it sf-sandbox bash
sf discuss
```
With Docker Compose, replace `docker sandbox exec` with `docker exec`.
@ -131,7 +131,7 @@ docker compose -f docker/docker-compose.yaml build --build-arg SF_VERSION=2.51.0
```bash
# Docker Sandbox
docker sandbox rm gsd-sandbox
docker sandbox rm sf-sandbox
# Docker Compose
docker compose -f docker/docker-compose.yaml down -v

6
docs/README.md
View file

@ -27,8 +27,8 @@ Simplified Chinese translation: [`zh-CN/`](./zh-CN/).
| [Working in Teams](./user-docs/working-in-teams.md) | Unique milestone IDs, `.gitignore` setup, and shared planning artifacts |
| [Skills](./user-docs/skills.md) | Bundled skills, skill discovery, and custom skill authoring |
| [Migration from v1](./user-docs/migration.md) | Migrating `.planning` directories from the original SF |
| [Troubleshooting](./user-docs/troubleshooting.md) | Common issues, `/gsd doctor` (real-time visibility v2.40), `/gsd forensics` (full debugger v2.40), and recovery procedures |
| [Web Interface](./user-docs/web-interface.md) | Browser-based project management with `gsd --web` (v2.41) |
| [Troubleshooting](./user-docs/troubleshooting.md) | Common issues, `/sf doctor` (real-time visibility v2.40), `/sf forensics` (full debugger v2.40), and recovery procedures |
| [Web Interface](./user-docs/web-interface.md) | Browser-based project management with `sf --web` (v2.41) |
| [VS Code Extension](../vscode-extension/README.md) | Chat participant, sidebar dashboard, and RPC integration for VS Code |
## Architecture & Internals
@ -43,7 +43,7 @@ Design documents, ADRs, and internal references. Located in [`dev/`](./dev/).
| [ADR-003: Pipeline Simplification](./dev/ADR-003-pipeline-simplification.md) | Research merged into planning, mechanical completion (v2.30) |
| [ADR-004: Capability-Aware Model Routing](./dev/ADR-004-capability-aware-model-routing.md) | Extend routing from tier/cost selection to task-capability matching |
| [ADR-007: Model Catalog Split](./dev/ADR-007-model-catalog-split.md) | Separate model metadata from routing logic for extensibility |
| [ADR-008: SF Tools over MCP](./dev/ADR-008-gsd-tools-over-mcp-for-provider-parity.md) | Native tools over MCP for provider parity |
| [ADR-008: SF Tools over MCP](./dev/ADR-008-sf-tools-over-mcp-for-provider-parity.md) | Native tools over MCP for provider parity |
| [ADR-008: Implementation Plan](./dev/ADR-008-IMPLEMENTATION-PLAN.md) | Implementation plan for ADR-008 |
| [Context Optimization Opportunities](./dev/pi-context-optimization-opportunities.md) | Analysis of context window usage and optimization strategies |
| [File System Map](./dev/FILE-SYSTEM-MAP.md) | Complete file system reference |

94
docs/dev/ADR-001-branchless-worktree-architecture.md
View file

@ -7,9 +7,9 @@
## Context
SF uses git for isolation during autonomous coding sessions. The current architecture (shipped in M003, v2.13.0) creates a **worktree per milestone** with **slice branches inside each worktree**. Each slice (`S01`, `S02`, ...) gets its own branch (`gsd/M001/S01`) within the worktree, which merges back to the milestone branch (`milestone/M001`) via `--no-ff` when the slice completes. The milestone branch squash-merges to `main` when the milestone completes.
SF uses git for isolation during autonomous coding sessions. The current architecture (shipped in M003, v2.13.0) creates a **worktree per milestone** with **slice branches inside each worktree**. Each slice (`S01`, `S02`, ...) gets its own branch (`sf/M001/S01`) within the worktree, which merges back to the milestone branch (`milestone/M001`) via `--no-ff` when the slice completes. The milestone branch squash-merges to `main` when the milestone completes.
This architecture replaced a previous "branch-per-slice" model that had severe `.gsd/` merge conflicts. M003 solved the merge conflicts but retained slice branches inside worktrees, inheriting complexity that has produced persistent, user-facing failures.
This architecture replaced a previous "branch-per-slice" model that had severe `.sf/` merge conflicts. M003 solved the merge conflicts but retained slice branches inside worktrees, inheriting complexity that has produced persistent, user-facing failures.
### Problems
@ -19,11 +19,11 @@ When `research-slice` or `plan-slice` dispatches, the agent writes artifacts (e.
Documented in the auto-stop architecture doc as "The Branch-Switching Problem."
**2. `.gsd/` state clobbering across branches**
**2. `.sf/` state clobbering across branches**
`.gsd/` is gitignored (line 52 of `.gitignore`: `.gsd/`). Planning artifacts (roadmaps, plans, summaries, decisions, requirements) live in `.gsd/milestones/` but are invisible to git. When multiple branches or worktrees operate from the same repo, they share a single `.gsd/` directory on disk. Branch A's M001 roadmap overwrites Branch B's M001 roadmap. SF reads corrupted state, shows wrong milestone as complete, or enters infinite dispatch loops.
`.sf/` is gitignored (line 52 of `.gitignore`: `.sf/`). Planning artifacts (roadmaps, plans, summaries, decisions, requirements) live in `.sf/milestones/` but are invisible to git. When multiple branches or worktrees operate from the same repo, they share a single `.sf/` directory on disk. Branch A's M001 roadmap overwrites Branch B's M001 roadmap. SF reads corrupted state, shows wrong milestone as complete, or enters infinite dispatch loops.
The codebase has a contradictory workaround: `smartStage()` (git-service.ts:304-352) force-adds `SF_DURABLE_PATHS` (milestones/, DECISIONS.md, PROJECT.md, REQUIREMENTS.md, QUEUE.md) despite the `.gitignore`. This means `.gsd/milestones/` IS partially tracked on some branches but the gitignore claims otherwise. The code fights the configuration.
The codebase has a contradictory workaround: `smartStage()` (git-service.ts:304-352) force-adds `SF_DURABLE_PATHS` (milestones/, DECISIONS.md, PROJECT.md, REQUIREMENTS.md, QUEUE.md) despite the `.gitignore`. This means `.sf/milestones/` IS partially tracked on some branches but the gitignore claims otherwise. The code fights the configuration.
**3. Merge/conflict code complexity**
@ -33,7 +33,7 @@ The current slice branch model requires:
- `git-self-heal.ts` — 198 lines, 3 recovery functions for merge failures
- `fix-merge` dispatch unit — dedicated LLM session to resolve conflicts the auto-resolver can't handle
- `smartStage()` — 49 lines of runtime exclusion during staging
- Conflict categorization — 80 lines classifying `.gsd/` vs runtime vs code conflicts
- Conflict categorization — 80 lines classifying `.sf/` vs runtime vs code conflicts
Total: **~582 lines** of merge/branch/conflict code across 3 files, plus the `fix-merge` prompt template and dispatch logic. This code exists solely because of slice branches.
@ -45,14 +45,14 @@ Branch-mode (`git-service.ts:mergeSliceToMain`) and worktree-mode (`auto-worktre
- v2.11.1: URGENT fix for parse cache staleness causing repeated unit dispatch (directly caused by branch switching invalidation timing)
- v2.13.1: Windows hotfix for multi-line commit messages in `mergeSliceToMilestone`
- 15+ separate bug fixes for `.gsd/` merge conflicts in the pre-M003 era
- 15+ separate bug fixes for `.sf/` merge conflicts in the pre-M003 era
- Persistent user complaints about loop detection failures and state corruption
## Decision
**Eliminate slice branches entirely.** All work within a milestone worktree commits sequentially on a single branch (`milestone/<MID>`). No branch creation, no branch switching, no slice merges, no conflict resolution within a worktree.
Track `.gsd/` planning artifacts in git. Gitignore only runtime/ephemeral state.
Track `.sf/` planning artifacts in git. Gitignore only runtime/ephemeral state.
### The Architecture
@ -92,49 +92,49 @@ main ─────────────────────────
| Branch switching | Never happens. All work on one branch. |
| Conflict resolution | No merges within a worktree means no conflicts within a worktree. |
### `.gsd/` Tracking Model
### `.sf/` Tracking Model
**Tracked in git (travels with the branch):**
```
.gsd/milestones/ — roadmaps, plans, summaries, research, contexts, task plans/summaries
.gsd/PROJECT.md — project overview
.gsd/DECISIONS.md — architectural decision register
.gsd/REQUIREMENTS.md — requirements register
.gsd/QUEUE.md — work queue
.sf/milestones/ — roadmaps, plans, summaries, research, contexts, task plans/summaries
.sf/PROJECT.md — project overview
.sf/DECISIONS.md — architectural decision register
.sf/REQUIREMENTS.md — requirements register
.sf/QUEUE.md — work queue
```
**Gitignored (ephemeral, runtime, infrastructure):**
```
.gsd/runtime/ — dispatch records, timeout tracking
.gsd/activity/ — JSONL session dumps
.gsd/worktrees/ — git worktree working directories
.gsd/auto.lock — crash detection sentinel
.gsd/metrics.json — token/cost accumulator
.gsd/completed-units.json — dispatch idempotency tracker
.gsd/STATE.md — derived state cache (rebuilt by deriveState())
.gsd/gsd.db — SQLite cache (rebuilt from tracked markdown by importers)
.gsd/DISCUSSION-MANIFEST.json — discussion phase tracking
.gsd/milestones/**/*-CONTINUE.md — interrupted-work markers
.gsd/milestones/**/continue.md — legacy continue markers
.sf/runtime/ — dispatch records, timeout tracking
.sf/activity/ — JSONL session dumps
.sf/worktrees/ — git worktree working directories
.sf/auto.lock — crash detection sentinel
.sf/metrics.json — token/cost accumulator
.sf/completed-units.json — dispatch idempotency tracker
.sf/STATE.md — derived state cache (rebuilt by deriveState())
.sf/sf.db — SQLite cache (rebuilt from tracked markdown by importers)
.sf/DISCUSSION-MANIFEST.json — discussion phase tracking
.sf/milestones/**/*-CONTINUE.md — interrupted-work markers
.sf/milestones/**/continue.md — legacy continue markers
```
### `.gitignore` Update
Replace the current blanket `.gsd/` ignore with explicit runtime-only ignores:
Replace the current blanket `.sf/` ignore with explicit runtime-only ignores:
```gitignore
# ── SF: Runtime / Ephemeral ─────────────────────────────────
.gsd/auto.lock
.gsd/completed-units.json
.gsd/STATE.md
.gsd/metrics.json
.gsd/gsd.db
.gsd/activity/
.gsd/runtime/
.gsd/worktrees/
.gsd/DISCUSSION-MANIFEST.json
.gsd/milestones/**/*-CONTINUE.md
.gsd/milestones/**/continue.md
.sf/auto.lock
.sf/completed-units.json
.sf/STATE.md
.sf/metrics.json
.sf/sf.db
.sf/activity/
.sf/runtime/
.sf/worktrees/
.sf/DISCUSSION-MANIFEST.json
.sf/milestones/**/*-CONTINUE.md
.sf/milestones/**/continue.md
```
Planning artifacts (milestones/, PROJECT.md, DECISIONS.md, REQUIREMENTS.md, QUEUE.md) are NOT in `.gitignore` and are tracked normally.
@ -163,7 +163,7 @@ The function simplifies dramatically:
5. `git commit` with milestone summary
6. Remove worktree + delete branch
No conflict categorization. No runtime file stripping. No `.gsd/` special handling. Planning artifacts merge cleanly because they're in `.gsd/milestones/M001/` which doesn't exist on `main` until this merge.
No conflict categorization. No runtime file stripping. No `.sf/` special handling. Planning artifacts merge cleanly because they're in `.sf/milestones/M001/` which doesn't exist on `main` until this merge.
### What `smartStage()` Becomes
@ -192,7 +192,7 @@ The `fix-merge` dispatch unit type is eliminated. Within a worktree, there are n
The `shouldUseWorktreeIsolation()` three-tier preference resolution is replaced by a single behavior: worktree isolation is always used. The `git.isolation: "branch"` preference is deprecated.
Projects with existing `gsd/M001/S01` slice branches can still be read by state derivation, but new work never creates slice branches.
Projects with existing `sf/M001/S01` slice branches can still be read by state derivation, but new work never creates slice branches.
### Risks
@ -209,7 +209,7 @@ Squash merge collapses all commits into one on `main`. Mitigations:
**3. SQLite DB desync after `git reset`**
If tracked markdown rolls back via `git reset --hard`, the gitignored `gsd.db` doesn't. Mitigation: the importer layer (M001/S02) rebuilds the DB from markdown on startup. The DB is a cache, markdown is truth.
If tracked markdown rolls back via `git reset --hard`, the gitignored `sf.db` doesn't. Mitigation: the importer layer (M001/S02) rebuilds the DB from markdown on startup. The DB is a cache, markdown is truth.
**4. Disk space with multiple worktrees**
@ -223,15 +223,15 @@ After `research-slice` or `plan-slice`, immediately merge the slice branch back
**Rejected:** Adds another merge path instead of removing the root cause. Still requires conflict resolution, self-healing, branch switching.
### B. Keep `.gsd/` gitignored, bootstrap from git history for manual worktrees
### B. Keep `.sf/` gitignored, bootstrap from git history for manual worktrees
When SF detects an empty `.gsd/` in a worktree, reconstruct state from the branch's git history using `git show <commit>:.gsd/...`.
When SF detects an empty `.sf/` in a worktree, reconstruct state from the branch's git history using `git show <commit>:.sf/...`.
**Rejected:** Recovery logic, not architecture. Doesn't fix the fundamental problem of branch-agnostic state. Fails when git history has been rewritten.
### C. Branch-scoped `.gsd/` directories (`.gsd/branches/<branch-name>/milestones/...`)
### C. Branch-scoped `.sf/` directories (`.sf/branches/<branch-name>/milestones/...`)
Each branch writes to a namespaced subdirectory within `.gsd/`.
Each branch writes to a namespaced subdirectory within `.sf/`.
**Rejected:** Adds complexity instead of removing it. Requires renaming/moving on branch creation, doesn't work with standard git tools (`git checkout` doesn't rename directories).
@ -243,7 +243,7 @@ This architecture was stress-tested by three independent models:
**GPT-5.4 (Codex)** read the full codebase and confirmed the model is sound. Identified that `smartStage()` already force-adds durable paths (validating the tracked-artifact approach) and that `resolveMainWorktreeRoot` in PR #487 is architecturally wrong (adopted — PR to be closed).
**Codebase analysis** confirmed `.gsd/milestones/` is already partially tracked on `main` despite the `.gitignore`, that `SF_DURABLE_PATHS` exists as a code-level acknowledgment that planning artifacts should be tracked, and that the README already documents the correct runtime-only gitignore pattern.
**Codebase analysis** confirmed `.sf/milestones/` is already partially tracked on `main` despite the `.gitignore`, that `SF_DURABLE_PATHS` exists as a code-level acknowledgment that planning artifacts should be tracked, and that the README already documents the correct runtime-only gitignore pattern.
### Codex (GPT-5.4) Dissent — "No Slice Branches Is a Redesign"
@ -255,7 +255,7 @@ Rebuttal: In the branchless model, there is no integration step to crash between
**Concern 2: "Concurrent edits to shared root docs (PROJECT.md, DECISIONS.md) from two terminals."**
Rebuttal: Valid edge case. If `/gsd queue` edits `DECISIONS.md` on `main` while auto-mode edits it in a worktree, there's a content conflict at squash-merge time. This is a standard git content conflict — no different from two developers editing the same file. Handled by normal merge resolution. Not caused by or solved by slice branches.
Rebuttal: Valid edge case. If `/sf queue` edits `DECISIONS.md` on `main` while auto-mode edits it in a worktree, there's a content conflict at squash-merge time. This is a standard git content conflict — no different from two developers editing the same file. Handled by normal merge resolution. Not caused by or solved by slice branches.
**Concern 3: "Slice→milestone merges provide continuous integration. Removing them pushes conflict discovery to the end."**
@ -263,7 +263,7 @@ Rebuttal: In a single-user sequential workflow, there is nothing to integrate ag
**Concern 4: "Replace slice branches with another explicit slice-boundary primitive. Don't just delete them."**
Response: Accepted in spirit. Commits with conventional tags (`feat(M001/S01):`, `feat(M001/S01/T01):`) serve as the slice boundary primitive. `git log --grep="M001/S01"` isolates a slice's history. `git revert` targets specific commits. Git tags (`gsd/M001/S01-complete`) can mark slice completion if needed. The boundary primitive is commit metadata, not branches.
Response: Accepted in spirit. Commits with conventional tags (`feat(M001/S01):`, `feat(M001/S01/T01):`) serve as the slice boundary primitive. `git log --grep="M001/S01"` isolates a slice's history. `git revert` targets specific commits. Git tags (`sf/M001/S01-complete`) can mark slice completion if needed. The boundary primitive is commit metadata, not branches.
## Action Items

8
docs/dev/ADR-003-pipeline-simplification.md
View file

@ -144,7 +144,7 @@ For the same 4-slice, 3-task milestone:
- The plan-milestone prompt drops "Trust the research" — there is no research document to trust.
- The RESEARCH.md artifact becomes optional. If the planner wants to capture notes for downstream reference, it can write one. But it's not required, and downstream units don't depend on it.
- Skill discovery instructions move into the plan-milestone prompt.
- The research-milestone template (`prompts/research-milestone.md`) is retained but only used when explicitly dispatched via `/gsd dispatch research`.
- The research-milestone template (`prompts/research-milestone.md`) is retained but only used when explicitly dispatched via `/sf dispatch research`.
**Token savings:** ~1 full session (12–37K tokens of prompt context) + the RESEARCH.md document no longer re-inlined into plan-milestone (~5–15K tokens).
@ -231,7 +231,7 @@ The aggregator reads `T##-VERIFY.json` as the primary source of truth, supplemen
- A new `aggregateMilestoneVerification()` function collects `T##-VERIFY.json` files and `S##-UAT-RESULT.md` files across all slices.
- The function produces a VALIDATION.md with per-task and per-slice pass/fail status, UAT evidence, and an overall verdict.
- The LLM-driven validate-milestone session is removed from the default pipeline.
- The validate-milestone template is retained for explicit dispatch (users who want LLM-driven validation can run `/gsd dispatch validate`).
- The validate-milestone template is retained for explicit dispatch (users who want LLM-driven validation can run `/sf dispatch validate`).
- The `skip_milestone_validation` preference (which writes a pass-through VALIDATION.md) becomes the default behavior, with the mechanical aggregation replacing it.
```typescript
@ -571,7 +571,7 @@ At current Opus pricing ($15/MTok input, $75/MTok output — as of March 2026),
- The **crash recovery**, **idempotency**, and **stuck detection** systems (fewer sessions means these fire less often, but the safety nets remain)
- The **metrics** and **cost tracking** systems
- The **parallel orchestrator** for independent milestones
- All prompt templates are **retained** — for fallback, recovery, and explicit dispatch via `/gsd dispatch <unit-type>`
- All prompt templates are **retained** — for fallback, recovery, and explicit dispatch via `/sf dispatch <unit-type>`
### What Gets Simpler Downstream
@ -683,7 +683,7 @@ The mechanical summary quality might be insufficient for complex slices.
4. Remove dispatch rule "planning (no research, not S01) → research-slice"
5. Update `plan-milestone.md` and `plan-slice.md` prompt templates
6. Make `skip_research` and `skip_slice_research` preferences default to true (backwards compat)
7. Retain research templates for explicit `/gsd dispatch research` use
7. Retain research templates for explicit `/sf dispatch research` use
8. **Targeted inlining reduction for planning sessions:** Move DECISIONS, REQUIREMENTS, PROJECT to path references in plan-milestone and plan-slice prompts. Keep ROADMAP and CONTEXT inlined. This prevents context pressure from the added exploration work.
### Phase 2: Mechanical slice completion

2
docs/dev/ADR-004-capability-aware-model-routing.md
View file

@ -232,7 +232,7 @@ Partial overrides are deep-merged with built-in defaults. This uses the same `mo
### Profile Versioning
Built-in capability profiles are maintained alongside the existing `MODEL_CAPABILITY_TIER` and `MODEL_COST_PER_1K_INPUT` tables in `model-router.ts`. When the `@gsd/pi-ai` model catalog is updated with new models, the capability profile table must be updated in the same PR. A linting rule should flag any model present in `MODEL_CAPABILITY_TIER` but missing from `MODEL_CAPABILITY_PROFILES`.
Built-in capability profiles are maintained alongside the existing `MODEL_CAPABILITY_TIER` and `MODEL_COST_PER_1K_INPUT` tables in `model-router.ts`. When the `@sf/pi-ai` model catalog is updated with new models, the capability profile table must be updated in the same PR. A linting rule should flag any model present in `MODEL_CAPABILITY_TIER` but missing from `MODEL_CAPABILITY_PROFILES`.
Profiles are versioned implicitly by SF release. The existing `models.json` `modelOverrides` mechanism allows users to correct stale defaults immediately without waiting for a SF update.

4
docs/dev/ADR-005-multi-model-provider-tool-strategy.md
View file

@ -63,5 +63,5 @@ Introduce a provider capability registry and tool compatibility layer that integ
| `packages/pi-ai/src/providers/transform-messages.ts` | Cross-provider normalization |
| `packages/pi-ai/src/types.ts` | Core types |
| `packages/pi-coding-agent/src/core/extensions/types.ts` | ToolDefinition, ExtensionAPI |
| `src/resources/extensions/gsd/model-router.ts` | Capability scoring (ADR-004) |
| `src/resources/extensions/gsd/auto-model-selection.ts` | Model selection orchestration |
| `src/resources/extensions/sf/model-router.ts` | Capability scoring (ADR-004) |
| `src/resources/extensions/sf/auto-model-selection.ts` | Model selection orchestration |

2
docs/dev/ADR-007-model-catalog-split.md
View file

@ -243,7 +243,7 @@ Make all providers load on-demand via async dynamic imports, generalizing the Be
### 2. Plugin architecture with separate npm packages
Move each provider to its own package (`@gsd/provider-anthropic`, etc.). Maximum isolation but dramatically more complex build/release/versioning. Overkill for a monorepo where all providers ship together.
Move each provider to its own package (`@sf/provider-anthropic`, etc.). Maximum isolation but dramatically more complex build/release/versioning. Overkill for a monorepo where all providers ship together.
### 3. Do nothing

24
docs/dev/ADR-008-IMPLEMENTATION-PLAN.md
View file

@ -1,6 +1,6 @@
# ADR-008 Implementation Plan
**Related ADR:** [ADR-008-gsd-tools-over-mcp-for-provider-parity.md](/Users/jeremymcspadden/Github/gsd-2/docs/ADR-008-gsd-tools-over-mcp-for-provider-parity.md)
**Related ADR:** [ADR-008-sf-tools-over-mcp-for-provider-parity.md](/Users/jeremymcspadden/Github/sf-2/docs/ADR-008-sf-tools-over-mcp-for-provider-parity.md)
**Status:** Draft
**Date:** 2026-04-09
@ -36,9 +36,9 @@ Goal: separate business logic from transport registration.
Targets:
- `src/resources/extensions/gsd/bootstrap/db-tools.ts`
- `src/resources/extensions/gsd/bootstrap/query-tools.ts`
- `src/resources/extensions/gsd/tools/complete-task.ts`
- `src/resources/extensions/sf/bootstrap/db-tools.ts`
- `src/resources/extensions/sf/bootstrap/query-tools.ts`
- `src/resources/extensions/sf/tools/complete-task.ts`
- sibling modules used by planning/summary/validation tools
Deliverables:
@ -80,7 +80,7 @@ Likely files:
Decisions to make during implementation:
- extend existing MCP package vs create `packages/mcp-gsd-tools-server`
- extend existing MCP package vs create `packages/mcp-sf-tools-server`
- canonical names only vs selected alias export
- single combined server vs separate “session” and “workflow” server modes
@ -95,7 +95,7 @@ Goal: ensure MCP mutations enforce the same rules as native tool calls.
Targets:
- `src/resources/extensions/gsd/bootstrap/write-gate.ts`
- `src/resources/extensions/sf/bootstrap/write-gate.ts`
- any current tool-call gating hooks tied to native runtime only
- MCP wrapper layer before shared handler invocation
@ -158,7 +158,7 @@ Goal: keep the workflow contract strict while removing transport assumptions fro
Targets:
- `src/resources/extensions/gsd/prompts/execute-task.md`
- `src/resources/extensions/sf/prompts/execute-task.md`
- related planning/discuss prompts that reference tool availability
- provider and MCP docs
@ -251,16 +251,16 @@ Verification:
High-probability files for the first implementation:
- `src/resources/extensions/gsd/bootstrap/db-tools.ts`
- `src/resources/extensions/gsd/bootstrap/query-tools.ts`
- `src/resources/extensions/gsd/bootstrap/write-gate.ts`
- `src/resources/extensions/gsd/tools/complete-task.ts`
- `src/resources/extensions/sf/bootstrap/db-tools.ts`
- `src/resources/extensions/sf/bootstrap/query-tools.ts`
- `src/resources/extensions/sf/bootstrap/write-gate.ts`
- `src/resources/extensions/sf/tools/complete-task.ts`
- `src/resources/extensions/claude-code-cli/stream-adapter.ts`
- `src/resources/extensions/claude-code-cli/index.ts`
- `packages/mcp-server/src/server.ts`
- `packages/mcp-server/src/session-manager.ts`
- `packages/mcp-server/README.md`
- `src/resources/extensions/gsd/prompts/execute-task.md`
- `src/resources/extensions/sf/prompts/execute-task.md`
## Testing Strategy

4
docs/dev/ADR-008-gsd-tools-over-mcp-for-provider-parity.md
View file

@ -3,7 +3,7 @@
**Status:** Proposed
**Date:** 2026-04-09
**Deciders:** Jeremy McSpadden
**Related:** ADR-004 (capability-aware model routing), ADR-007 (model catalog split and provider API encapsulation), `src/resources/extensions/gsd/bootstrap/db-tools.ts`, `src/resources/extensions/claude-code-cli/stream-adapter.ts`, `packages/mcp-server/src/server.ts`
**Related:** ADR-004 (capability-aware model routing), ADR-007 (model catalog split and provider API encapsulation), `src/resources/extensions/sf/bootstrap/db-tools.ts`, `src/resources/extensions/claude-code-cli/stream-adapter.ts`, `packages/mcp-server/src/server.ts`
## Context
@ -29,7 +29,7 @@ The core SF workflow tools are internal extension tools. Examples include:
- `gsd_replan_slice`
- `gsd_reassess_roadmap`
These are registered in `src/resources/extensions/gsd/bootstrap/db-tools.ts` and related bootstrap files. SF prompts assume these tools are available during discuss, plan, and execute flows.
These are registered in `src/resources/extensions/sf/bootstrap/db-tools.ts` and related bootstrap files. SF prompts assume these tools are available during discuss, plan, and execute flows.
Separately, `packages/mcp-server/src/server.ts` exposes a different tool surface:

74
docs/dev/ADR-009-IMPLEMENTATION-PLAN.md
View file

@ -1,6 +1,6 @@
# ADR-009 Implementation Plan
**Related ADR:** [ADR-009-orchestration-kernel-refactor.md](/Users/jeremymcspadden/Github/gsd-2/docs/dev/ADR-009-orchestration-kernel-refactor.md)
**Related ADR:** [ADR-009-orchestration-kernel-refactor.md](/Users/jeremymcspadden/Github/sf-2/docs/dev/ADR-009-orchestration-kernel-refactor.md)
**Status:** Draft
**Date:** 2026-04-14
**Target Window:** 8-10 waves (incremental, no big-bang rewrite)
@ -49,10 +49,10 @@ Goal: define typed contracts and a new orchestration spine without changing beha
Primary targets:
- `src/resources/extensions/gsd/auto.ts`
- `src/resources/extensions/gsd/auto/loop.ts`
- `src/resources/extensions/gsd/auto/types.ts`
- `src/resources/extensions/gsd/auto/session.ts`
- `src/resources/extensions/sf/auto.ts`
- `src/resources/extensions/sf/auto/loop.ts`
- `src/resources/extensions/sf/auto/types.ts`
- `src/resources/extensions/sf/auto/session.ts`
Deliverables:
@ -66,11 +66,11 @@ Goal: normalize all checks into a unified gate runner.
Primary targets:
- `src/resources/extensions/gsd/verification-gate.ts`
- `src/resources/extensions/gsd/auto-verification.ts`
- `src/resources/extensions/gsd/pre-execution-checks.ts`
- `src/resources/extensions/gsd/post-execution-checks.ts`
- `src/resources/extensions/gsd/milestone-validation-gates.ts`
- `src/resources/extensions/sf/verification-gate.ts`
- `src/resources/extensions/sf/auto-verification.ts`
- `src/resources/extensions/sf/pre-execution-checks.ts`
- `src/resources/extensions/sf/post-execution-checks.ts`
- `src/resources/extensions/sf/milestone-validation-gates.ts`
Deliverables:
@ -84,11 +84,11 @@ Goal: enable any-model-any-phase through requirement-based selection plus policy
Primary targets:
- `src/resources/extensions/gsd/model-router.ts`
- `src/resources/extensions/gsd/auto-model-selection.ts`
- `src/resources/extensions/gsd/preferences-models.ts`
- `src/resources/extensions/gsd/model-cost-table.ts`
- `src/resources/extensions/gsd/custom-execution-policy.ts`
- `src/resources/extensions/sf/model-router.ts`
- `src/resources/extensions/sf/auto-model-selection.ts`
- `src/resources/extensions/sf/preferences-models.ts`
- `src/resources/extensions/sf/model-cost-table.ts`
- `src/resources/extensions/sf/custom-execution-policy.ts`
Deliverables:
@ -103,11 +103,11 @@ Goal: move to one DAG scheduler contract.
Primary targets:
- `src/resources/extensions/gsd/reactive-graph.ts`
- `src/resources/extensions/gsd/slice-parallel-orchestrator.ts`
- `src/resources/extensions/gsd/parallel-orchestrator.ts`
- `src/resources/extensions/gsd/graph.ts`
- `src/resources/extensions/gsd/unit-runtime.ts`
- `src/resources/extensions/sf/reactive-graph.ts`
- `src/resources/extensions/sf/slice-parallel-orchestrator.ts`
- `src/resources/extensions/sf/parallel-orchestrator.ts`
- `src/resources/extensions/sf/graph.ts`
- `src/resources/extensions/sf/unit-runtime.ts`
Deliverables:
@ -121,10 +121,10 @@ Goal: guarantee git action and metadata record per turn.
Primary targets:
- `src/resources/extensions/gsd/git-service.ts`
- `src/resources/extensions/gsd/auto-post-unit.ts`
- `src/resources/extensions/gsd/auto-unit-closeout.ts`
- `src/resources/extensions/gsd/auto-worktree.ts`
- `src/resources/extensions/sf/git-service.ts`
- `src/resources/extensions/sf/auto-post-unit.ts`
- `src/resources/extensions/sf/auto-unit-closeout.ts`
- `src/resources/extensions/sf/auto-worktree.ts`
Deliverables:
@ -138,11 +138,11 @@ Goal: unify journal/activity/metrics into a causal event model.
Primary targets:
- `src/resources/extensions/gsd/journal.ts`
- `src/resources/extensions/gsd/activity-log.ts`
- `src/resources/extensions/gsd/metrics.ts`
- `src/resources/extensions/gsd/workflow-logger.ts`
- `src/resources/extensions/gsd/gsd-db.ts`
- `src/resources/extensions/sf/journal.ts`
- `src/resources/extensions/sf/activity-log.ts`
- `src/resources/extensions/sf/metrics.ts`
- `src/resources/extensions/sf/workflow-logger.ts`
- `src/resources/extensions/sf/sf-db.ts`
Deliverables:
@ -156,11 +156,11 @@ Goal: formal multi-round clarify/research/draft/compile flow.
Primary targets:
- `src/resources/extensions/gsd/guided-flow.ts`
- `src/resources/extensions/gsd/preparation.ts`
- `src/resources/extensions/gsd/auto/phases.ts`
- `src/resources/extensions/gsd/auto-prompts.ts`
- prompt templates under `src/resources/extensions/gsd/prompts/`
- `src/resources/extensions/sf/guided-flow.ts`
- `src/resources/extensions/sf/preparation.ts`
- `src/resources/extensions/sf/auto/phases.ts`
- `src/resources/extensions/sf/auto-prompts.ts`
- prompt templates under `src/resources/extensions/sf/prompts/`
Deliverables:
@ -219,7 +219,7 @@ Exit criteria:
Verification:
- targeted tests in `src/resources/extensions/gsd/tests/*auto*`
- targeted tests in `src/resources/extensions/sf/tests/*auto*`
- `npm run test:unit`
## Wave 2: Gate Plane Unification
@ -288,7 +288,7 @@ Verification:
- `slice-parallel-orchestrator.test.ts`
- `slice-parallel-conflict.test.ts`
- `sidecar-queue.test.ts`
- integration: `src/resources/extensions/gsd/tests/integration/*.test.ts`
- integration: `src/resources/extensions/sf/tests/integration/*.test.ts`
## Wave 5: GitOps Transactions Per Turn
@ -429,7 +429,7 @@ Verification:
Expected schema additions:
- audit projection tables in `gsd.db`
- audit projection tables in `sf.db`
- gate result persistence tables
- turn transaction metadata

2
docs/dev/ADR-009-orchestration-kernel-refactor.md
View file

@ -320,7 +320,7 @@ Primary decomposition targets:
- `auto.ts` -> orchestrator kernel + adapters
- `auto-prompts.ts` -> plan compiler + prompt renderers
- `state.ts` -> state query service + immutable state views
- `gsd-db.ts` -> data access layer + event projection store
- `sf-db.ts` -> data access layer + event projection store
- `auto-post-unit.ts` / `auto-verification.ts` -> closeout gate services
## Acceptance Criteria

90
docs/dev/ADR-010-pi-clean-seam-architecture.md
View file

@ -13,10 +13,10 @@ SF vendors four packages from [pi-mono](https://github.com/badlogic/pi-mono) (an
| Package | Role | Current version |
|---|---|---|
| `@gsd/pi-agent-core` | Core agent loop and types | 0.57.1 |
| `@gsd/pi-ai` | Multi-provider LLM API | 0.57.1 |
| `@gsd/pi-tui` | Terminal UI framework | 0.57.1 |
| `@gsd/pi-coding-agent` | Coding agent, tools, extension system | 2.74.0 |
| `@sf/pi-agent-core` | Core agent loop and types | 0.57.1 |
| `@sf/pi-ai` | Multi-provider LLM API | 0.57.1 |
| `@sf/pi-tui` | Terminal UI framework | 0.57.1 |
| `@sf/pi-coding-agent` | Coding agent, tools, extension system | 2.74.0 |
Vendoring was chosen over npm dependencies to allow SF to modify the upstream packages freely. However, over time, SF has written substantial original logic directly inside `pi-coding-agent` — approximately 79 files including:
@ -32,7 +32,7 @@ This SF-authored code is mixed in with upstream pi code inside the same package.
Pi-mono does publish to npm as `@mariozechner/pi-*`. Moving to npm dependencies would eliminate vendoring entirely, but it is blocked by:
1. `@gsd/native` bindings are imported directly inside the vendored pi-tui and pi-coding-agent source — the upstream npm packages do not have these imports
1. `@sf/native` bindings are imported directly inside the vendored pi-tui and pi-coding-agent source — the upstream npm packages do not have these imports
2. ~50 direct source modification commits to the vendored packages since March 2026 would need to be evaluated individually
3. The upstream extension API (~25 events) is a subset of SF's extension system (~50+ events) — the delta would need to be re-architected before the move
@ -52,32 +52,32 @@ packages/
pi-ai/ # vendored upstream — no SF modifications
pi-tui/ # vendored upstream — no SF modifications
pi-coding-agent/ # vendored upstream + extension system (pi-typed, stays here)
gsd-agent-core/ # NEW — SF session orchestration layer
gsd-agent-modes/ # NEW — SF run modes and CLI layer
sf-agent-core/ # NEW — SF session orchestration layer
sf-agent-modes/ # NEW — SF run modes and CLI layer
```
### Dependency graph
```
sf-run (binary)
└── @gsd/agent-modes
├── @gsd/agent-core
│ ├── @gsd/pi-coding-agent
│ ├── @gsd/pi-agent-core
│ └── @gsd/pi-ai
└── @gsd/pi-coding-agent
├── @gsd/pi-agent-core
├── @gsd/pi-ai
└── @gsd/pi-tui
└── @sf/agent-modes
├── @sf/agent-core
│ ├── @sf/pi-coding-agent
│ ├── @sf/pi-agent-core
│ └── @sf/pi-ai
└── @sf/pi-coding-agent
├── @sf/pi-agent-core
├── @sf/pi-ai
└── @sf/pi-tui
```
Arrows point in one direction only. No cycles. The vendored pi packages have no knowledge of `@gsd/agent-core` or `@gsd/agent-modes`.
Arrows point in one direction only. No cycles. The vendored pi packages have no knowledge of `@sf/agent-core` or `@sf/agent-modes`.
---
## Package Specifications
### `@gsd/agent-core` (`packages/gsd-agent-core/`)
### `@sf/agent-core` (`packages/sf-agent-core/`)
**Purpose:** SF's session orchestration layer. Owns the `AgentSession` class, compaction, bash execution, system prompt construction, and the `createAgentSession()` factory that wires everything together.
@ -119,13 +119,13 @@ export { BlobStore } from './blob-store.js'
| `blob-store.ts` | External binary data management |
| `export-html/` | Session HTML export |
**Key dependency note:** `agent-session.ts` imports pi types directly (`Agent`, `AgentEvent`, `AgentMessage`, `AgentState`, `AgentTool`, `ThinkingLevel` from `@gsd/pi-agent-core`; `Model`, `Message` from `@gsd/pi-ai`). This is intentional — SF's session layer is pi-typed, not abstracting over pi. This makes the seam a clear seam, not an abstraction.
**Key dependency note:** `agent-session.ts` imports pi types directly (`Agent`, `AgentEvent`, `AgentMessage`, `AgentState`, `AgentTool`, `ThinkingLevel` from `@sf/pi-agent-core`; `Model`, `Message` from `@sf/pi-ai`). This is intentional — SF's session layer is pi-typed, not abstracting over pi. This makes the seam a clear seam, not an abstraction.
---
### `@gsd/agent-modes` (`packages/gsd-agent-modes/`)
### `@sf/agent-modes` (`packages/sf-agent-modes/`)
**Purpose:** SF's run-mode and CLI layer. Assembles the agent session (from `@gsd/agent-core`) with a specific interface: interactive TUI, headless RPC server, or print output. Contains the `main()` entry point logic invoked by the `gsd` binary.
**Purpose:** SF's run-mode and CLI layer. Assembles the agent session (from `@sf/agent-core`) with a specific interface: interactive TUI, headless RPC server, or print output. Contains the `main()` entry point logic invoked by the `sf` binary.
**Public API surface (exported from `index.ts`):**
@ -167,26 +167,26 @@ The extension system remains here because it is legitimately pi-typed. Extension
**Required update to extension loader:**
`src/core/extensions/loader.ts` maintains a `STATIC_BUNDLED_MODULES` map of packages that extensions can import at runtime. After the migration, `@gsd/agent-core` and `@gsd/agent-modes` must be added to this map so that extensions importing those packages continue to resolve correctly in compiled Bun binaries:
`src/core/extensions/loader.ts` maintains a `STATIC_BUNDLED_MODULES` map of packages that extensions can import at runtime. After the migration, `@sf/agent-core` and `@sf/agent-modes` must be added to this map so that extensions importing those packages continue to resolve correctly in compiled Bun binaries:
```typescript
// Before (current)
const STATIC_BUNDLED_MODULES = {
"@gsd/pi-agent-core": _bundledPiAgentCore,
"@gsd/pi-ai": _bundledPiAi,
"@gsd/pi-tui": _bundledPiTui,
"@gsd/pi-coding-agent": _bundledPiCodingAgent,
"@sf/pi-agent-core": _bundledPiAgentCore,
"@sf/pi-ai": _bundledPiAi,
"@sf/pi-tui": _bundledPiTui,
"@sf/pi-coding-agent": _bundledPiCodingAgent,
// ...
}
// After
const STATIC_BUNDLED_MODULES = {
"@gsd/pi-agent-core": _bundledPiAgentCore,
"@gsd/pi-ai": _bundledPiAi,
"@gsd/pi-tui": _bundledPiTui,
"@gsd/pi-coding-agent": _bundledPiCodingAgent,
"@gsd/agent-core": _bundledGsdAgentCore, // NEW
"@gsd/agent-modes": _bundledGsdAgentModes, // NEW
"@sf/pi-agent-core": _bundledPiAgentCore,
"@sf/pi-ai": _bundledPiAi,
"@sf/pi-tui": _bundledPiTui,
"@sf/pi-coding-agent": _bundledPiCodingAgent,
"@sf/agent-core": _bundledGsdAgentCore, // NEW
"@sf/agent-modes": _bundledGsdAgentModes, // NEW
// ...
}
```
@ -197,9 +197,9 @@ const STATIC_BUNDLED_MODULES = {
1. Download the new pi-mono release for the four vendored packages
2. Copy the upstream source into `packages/pi-agent-core/`, `pi-ai/`, `pi-tui/`, `pi-coding-agent/`
- Do not touch `packages/gsd-agent-core/` or `packages/gsd-agent-modes/`
- Do not touch `packages/sf-agent-core/` or `packages/sf-agent-modes/`
3. Run `tsc --noEmit` (or the build) across the workspace
4. Fix type errors in `@gsd/agent-core` and `@gsd/agent-modes` only
4. Fix type errors in `@sf/agent-core` and `@sf/agent-modes` only
5. If upstream changed the extension event API, fix extension system integration in `pi-coding-agent/src/core/extensions/`
Steps 2-5 are scoped to known files. No archaeology required.
@ -210,9 +210,9 @@ Steps 2-5 are scoped to known files. No archaeology required.
| Issue | Location | Fix |
|---|---|---|
| Internal-path import of `AgentSessionEvent` | `src/web/bridge-service.ts` | Import from `@gsd/agent-core` public export |
| `clearQueue()` not in typed public API | `AgentSession` | Add to public interface in `@gsd/agent-core/index.ts` |
| `buildSessionContext()` on `SessionManager` | Used by SF code, not publicly exported | Evaluate: re-export from `@gsd/agent-core` or remove dependency |
| Internal-path import of `AgentSessionEvent` | `src/web/bridge-service.ts` | Import from `@sf/agent-core` public export |
| `clearQueue()` not in typed public API | `AgentSession` | Add to public interface in `@sf/agent-core/index.ts` |
| `buildSessionContext()` on `SessionManager` | Used by SF code, not publicly exported | Evaluate: re-export from `@sf/agent-core` or remove dependency |
| Deprecated `session_switch`, `session_fork`, `session_directory` usage | 2+ files in `pi-coding-agent` | Migrate to `session_start` with `reason` field (required for v0.65.0 compat) — can be done as part of or after clean seam work |
---
@ -222,9 +222,9 @@ Steps 2-5 are scoped to known files. No archaeology required.
### Positive
- Pi updates are scoped: type errors from a pi update surface only in the two new SF packages, not scattered across mixed source
- The module system enforces the boundary: a pi file importing `@gsd/agent-core` is a compiler error, not a convention violation
- The module system enforces the boundary: a pi file importing `@sf/agent-core` is a compiler error, not a convention violation
- Phase 2 (moving pi packages to npm) becomes a package.json change rather than a file archaeology project
- Headless/RPC consumers can depend on `@gsd/agent-core` without pulling in the TUI layer
- Headless/RPC consumers can depend on `@sf/agent-core` without pulling in the TUI layer
### Negative
@ -235,24 +235,24 @@ Steps 2-5 are scoped to known files. No archaeology required.
### Neutral
- End-user install experience (`npm install -g sf-run@latest`) is unchanged
- Extension authors see no change — the extension API surface remains in `@gsd/pi-coding-agent`
- Extension authors see no change — the extension API surface remains in `@sf/pi-coding-agent`
- SF packages continue to use pi types directly — no new abstraction layer
---
## Alternatives Considered
### Single `@gsd/agent` package
### Single `@sf/agent` package
Move everything into one package instead of two. Simpler dependency graph but creates a large package where session logic and TUI logic share a build unit. Rejected because headless/RPC use cases would pull in the TUI unnecessarily, and the two concerns have meaningfully different consumers.
### Directory convention within `pi-coding-agent` (no new packages)
Add a `src/gsd/` subdirectory inside `pi-coding-agent` to clearly mark SF files without creating new packages. Fastest to implement but the seam is a convention, not enforced by the module system. A future accidental cross-import would not be caught by the compiler. Rejected because the enforcement value of proper packages is worth the modest extra setup.
Add a `src/sf/` subdirectory inside `pi-coding-agent` to clearly mark SF files without creating new packages. Fastest to implement but the seam is a convention, not enforced by the module system. A future accidental cross-import would not be caught by the compiler. Rejected because the enforcement value of proper packages is worth the modest extra setup.
### Move to npm dependencies now (Phase 2 first)
Take `@mariozechner/pi-*` from npm and skip vendoring entirely. Blocked by `@gsd/native` imports baked into the vendored source, ~50 direct source modification commits, and the upstream extension API gap. Deferred to Phase 2.
Take `@mariozechner/pi-*` from npm and skip vendoring entirely. Blocked by `@sf/native` imports baked into the vendored source, ~50 direct source modification commits, and the upstream extension API gap. Deferred to Phase 2.
---
@ -261,11 +261,11 @@ Take `@mariozechner/pi-*` from npm and skip vendoring entirely. Blocked by `@gsd
The migration should proceed in this order to maintain a working build at each step:
1. **Audit** — identify all imports of `pi-coding-agent` internal paths (non-index) and document them
2. **Create packages** — scaffold `gsd-agent-core` and `gsd-agent-modes` with `package.json` and empty `index.ts`
2. **Create packages** — scaffold `sf-agent-core` and `sf-agent-modes` with `package.json` and empty `index.ts`
3. **Move files in batches** — start with leaf files (no downstream dependents within pi-coding-agent), work toward `agent-session.ts` last
4. **Fix imports incrementally** — TypeScript will identify broken imports after each batch
5. **Update extension loader** — add new packages to virtual module map
6. **Update build script** — insert new packages in dependency order
7. **Verify** — full build, existing tests pass, `gsd --version` works
7. **Verify** — full build, existing tests pass, `sf --version` works
The pi update to v0.67.2 (and the deprecated API migration) can be done as a follow-on once the clean seam is in place, since that work will be dramatically simpler with the new structure.

298
docs/dev/FILE-SYSTEM-MAP.md
View file

@ -84,7 +84,7 @@
| src/headless-events.ts | Headless Mode | Event classification, terminal detection, idle timeouts |
| src/headless-query.ts | Headless Mode, CLI | Read-only snapshot query (state, dispatch preview, costs) |
| src/headless-ui.ts | Headless Mode | Extension UI auto-response, progress formatting |
| src/headless.ts | Headless Mode | Orchestrator for /gsd subcommands without TUI via RPC |
| src/headless.ts | Headless Mode | Orchestrator for /sf subcommands without TUI via RPC |
| src/help-text.ts | CLI | Generates help text for all subcommands |
| src/loader.ts | Loader/Bootstrap | Fast-path startup, extension discovery/validation, env setup |
| src/logo.ts | CLI | ASCII logo rendering for welcome screen and loader |
@ -464,94 +464,94 @@
| File | System Label(s) | Description |
|------|-----------------|-------------|
| gsd/index.ts | SF Workflow | Main SF extension bootstrap and registration |
| gsd/auto.ts | Auto Engine | Automatic workflow execution and loop management |
| gsd/auto-dashboard.ts | Auto Engine, Web Mode | Real-time dashboard for auto-run progress |
| gsd/auto-worktree.ts | Auto Engine, Worktree | Automatic worktree creation and branch management |
| gsd/auto-recovery.ts | Auto Engine | Recovery for crashed/stalled workflows |
| gsd/auto-start.ts | Auto Engine | Initialization sequence for automatic execution |
| gsd/auto-worktree-sync.ts | Auto Engine, Worktree | State sync between worktrees and main |
| gsd/auto-model-selection.ts | Auto Engine, Model System | Intelligent LLM model routing |
| gsd/auto-direct-dispatch.ts | Auto Engine | Direct command dispatching without planning |
| gsd/auto-dispatch.ts | Auto Engine | Task queueing and priority-based dispatch |
| gsd/auto-timeout-recovery.ts | Auto Engine | Timeout handling and recovery |
| gsd/auto-post-unit.ts | Auto Engine | Post-unit milestone completion processing |
| gsd/auto-unit-closeout.ts | Auto Engine | Unit finalization and archiving |
| gsd/auto-verification.ts | Auto Engine | Post-execution verification |
| gsd/auto-timers.ts | Auto Engine | Timeout and deadline management |
| gsd/auto-loop.ts | Auto Engine, State Machine | Execution loop state and cycle management |
| gsd/auto-supervisor.ts | Auto Engine | Supervision and oversight of autonomous runs |
| gsd/auto-budget.ts | Auto Engine | Token/cost budgeting and tracking |
| gsd/auto-observability.ts | Auto Engine | Observability hooks and telemetry |
| gsd/auto-tool-tracking.ts | Auto Engine | Tool usage instrumentation |
| gsd/doctor.ts | Doctor/Diagnostics | Health check and system diagnostics |
| gsd/doctor-checks.ts | Doctor/Diagnostics | Individual diagnostic checks |
| gsd/doctor-providers.ts | Doctor/Diagnostics | Diagnostic data source providers |
| gsd/doctor-format.ts | Doctor/Diagnostics | Diagnostic output formatting |
| gsd/state.ts | State Machine | Milestone and workflow state management |
| gsd/history.ts | State Machine | State history and versioning |
| gsd/json-persistence.ts | State Machine | JSON-based persistence layer |
| gsd/memory-store.ts | State Machine | In-memory state storage |
| gsd/reactive-graph.ts | State Machine | Reactive dependency graph for state |
| gsd/routing-history.ts | State Machine | History of routing decisions |
| gsd/cache.ts | State Machine | Caching layer for performance |
| gsd/model-router.ts | Model System | LLM model selection and routing logic |
| gsd/worktree.ts | Worktree | Worktree creation and management |
| gsd/worktree-manager.ts | Worktree | Higher-level worktree orchestration |
| gsd/worktree-resolver.ts | Worktree | Worktree path and reference resolution |
| gsd/unit-runtime.ts | Auto Engine | Unit-level execution runtime |
| gsd/activity-log.ts | SF Workflow | Activity tracking and logging |
| gsd/debug-logger.ts | SF Workflow | Debug output and verbose logging |
| gsd/commands.ts | Commands | Main command dispatcher |
| gsd/commands-handlers.ts | Commands | Command-specific handlers |
| gsd/commands-bootstrap.ts | Commands | Bootstrap and initialization commands |
| gsd/commands-config.ts | Commands, Config | Configuration management commands |
| gsd/commands-extensions.ts | Commands, Extensions | Extension discovery and management |
| gsd/commands-inspect.ts | Commands, Doctor/Diagnostics | Database and state inspection tools |
| gsd/commands-logs.ts | Commands | Log viewing and filtering |
| gsd/commands-workflow-templates.ts | Commands, SF Workflow | Workflow template management |
| gsd/commands-cmux.ts | Commands, CMux | Tmux/cmux integration commands |
| gsd/exit-command.ts | Commands | Exit and cleanup commands |
| gsd/undo.ts | Commands | Undo and rollback functionality |
| gsd/kill.ts | Commands | Process termination and cleanup |
| gsd/worktree-command.ts | Commands, Worktree | Worktree subcommands |
| gsd/namespaced-resolver.ts | SF Workflow | Namespace and scoped resource resolution |
| gsd/error-utils.ts | SF Workflow | Error handling and formatting |
| gsd/errors.ts | SF Workflow | Error type definitions |
| gsd/diff-context.ts | SF Workflow | Diff-based context extraction |
| gsd/memory-extractor.ts | SF Workflow | Memory and context extraction from state |
| gsd/structured-data-formatter.ts | SF Workflow | Structured output formatting |
| gsd/export-html.ts | SF Workflow | HTML export of milestone reports |
| gsd/reports.ts | SF Workflow | Report generation and summaries |
| gsd/notifications.ts | SF Workflow | User notification and messaging |
| gsd/triage-ui.ts | SF Workflow | Triage interface for issue categorization |
| gsd/guided-flow.ts | SF Workflow | User-guided workflow orchestration |
| gsd/env-utils.ts | SF Workflow | Environment variable utilities |
| gsd/git-constants.ts | SF Workflow | Git-related constants and paths |
| gsd/milestone-id-utils.ts | SF Workflow | Milestone ID generation and parsing |
| gsd/resource-version.ts | SF Workflow | Resource versioning helpers |
| gsd/atomic-write.ts | SF Workflow | Atomic file write operations |
| gsd/captures.ts | SF Workflow | Artifact capture and storage |
| gsd/changelog.ts | SF Workflow | Changelog generation |
| gsd/claude-import.ts | SF Workflow | Claude API/resource importing |
| gsd/collision-diagnostics.ts | Doctor/Diagnostics | Collision detection and diagnostics |
| gsd/prompt-loader.ts | SF Workflow | Prompt template loading |
| gsd/file-watcher.ts | SF Workflow | File system change monitoring |
| gsd/parallel-eligibility.ts | SF Workflow | Parallel execution eligibility checks |
| gsd/plugin-importer.ts | SF Workflow, Extensions | Custom plugin/extension importing |
| gsd/verification-gate.ts | SF Workflow | Pre-execution verification checks |
| gsd/preference-models.ts | Config, Model System | Model preference configuration |
| gsd/preferences-skills.ts | Config, Skills | Skill preference configuration |
| gsd/post-unit-hooks.ts | SF Workflow | Post-unit execution hooks |
| gsd/skill-telemetry.ts | Skills | Skill usage and performance telemetry |
| gsd/bootstrap/* | SF Workflow, Loader/Bootstrap | Extension initialization and hook registration |
| gsd/auto/* | Auto Engine | Auto-execution engine components |
| gsd/commands/* | Commands | Command routing and handling |
| gsd/templates/* | SF Workflow | Output templates and formatters |
| gsd/prompts/* | SF Workflow | System prompts and instructions |
| gsd/workflow-templates/* | SF Workflow | Workflow starter templates and registry |
| gsd/skills/* | Skills | Integrated skill configurations |
| gsd/migrate/* | Migration | Data migration and upgrade tools |
| sf/index.ts | SF Workflow | Main SF extension bootstrap and registration |
| sf/auto.ts | Auto Engine | Automatic workflow execution and loop management |
| sf/auto-dashboard.ts | Auto Engine, Web Mode | Real-time dashboard for auto-run progress |
| sf/auto-worktree.ts | Auto Engine, Worktree | Automatic worktree creation and branch management |
| sf/auto-recovery.ts | Auto Engine | Recovery for crashed/stalled workflows |
| sf/auto-start.ts | Auto Engine | Initialization sequence for automatic execution |
| sf/auto-worktree-sync.ts | Auto Engine, Worktree | State sync between worktrees and main |
| sf/auto-model-selection.ts | Auto Engine, Model System | Intelligent LLM model routing |
| sf/auto-direct-dispatch.ts | Auto Engine | Direct command dispatching without planning |
| sf/auto-dispatch.ts | Auto Engine | Task queueing and priority-based dispatch |
| sf/auto-timeout-recovery.ts | Auto Engine | Timeout handling and recovery |
| sf/auto-post-unit.ts | Auto Engine | Post-unit milestone completion processing |
| sf/auto-unit-closeout.ts | Auto Engine | Unit finalization and archiving |
| sf/auto-verification.ts | Auto Engine | Post-execution verification |
| sf/auto-timers.ts | Auto Engine | Timeout and deadline management |
| sf/auto-loop.ts | Auto Engine, State Machine | Execution loop state and cycle management |
| sf/auto-supervisor.ts | Auto Engine | Supervision and oversight of autonomous runs |
| sf/auto-budget.ts | Auto Engine | Token/cost budgeting and tracking |
| sf/auto-observability.ts | Auto Engine | Observability hooks and telemetry |
| sf/auto-tool-tracking.ts | Auto Engine | Tool usage instrumentation |
| sf/doctor.ts | Doctor/Diagnostics | Health check and system diagnostics |
| sf/doctor-checks.ts | Doctor/Diagnostics | Individual diagnostic checks |
| sf/doctor-providers.ts | Doctor/Diagnostics | Diagnostic data source providers |
| sf/doctor-format.ts | Doctor/Diagnostics | Diagnostic output formatting |
| sf/state.ts | State Machine | Milestone and workflow state management |
| sf/history.ts | State Machine | State history and versioning |
| sf/json-persistence.ts | State Machine | JSON-based persistence layer |
| sf/memory-store.ts | State Machine | In-memory state storage |
| sf/reactive-graph.ts | State Machine | Reactive dependency graph for state |
| sf/routing-history.ts | State Machine | History of routing decisions |
| sf/cache.ts | State Machine | Caching layer for performance |
| sf/model-router.ts | Model System | LLM model selection and routing logic |
| sf/worktree.ts | Worktree | Worktree creation and management |
| sf/worktree-manager.ts | Worktree | Higher-level worktree orchestration |
| sf/worktree-resolver.ts | Worktree | Worktree path and reference resolution |
| sf/unit-runtime.ts | Auto Engine | Unit-level execution runtime |
| sf/activity-log.ts | SF Workflow | Activity tracking and logging |
| sf/debug-logger.ts | SF Workflow | Debug output and verbose logging |
| sf/commands.ts | Commands | Main command dispatcher |
| sf/commands-handlers.ts | Commands | Command-specific handlers |
| sf/commands-bootstrap.ts | Commands | Bootstrap and initialization commands |
| sf/commands-config.ts | Commands, Config | Configuration management commands |
| sf/commands-extensions.ts | Commands, Extensions | Extension discovery and management |
| sf/commands-inspect.ts | Commands, Doctor/Diagnostics | Database and state inspection tools |
| sf/commands-logs.ts | Commands | Log viewing and filtering |
| sf/commands-workflow-templates.ts | Commands, SF Workflow | Workflow template management |
| sf/commands-cmux.ts | Commands, CMux | Tmux/cmux integration commands |
| sf/exit-command.ts | Commands | Exit and cleanup commands |
| sf/undo.ts | Commands | Undo and rollback functionality |
| sf/kill.ts | Commands | Process termination and cleanup |
| sf/worktree-command.ts | Commands, Worktree | Worktree subcommands |
| sf/namespaced-resolver.ts | SF Workflow | Namespace and scoped resource resolution |
| sf/error-utils.ts | SF Workflow | Error handling and formatting |
| sf/errors.ts | SF Workflow | Error type definitions |
| sf/diff-context.ts | SF Workflow | Diff-based context extraction |
| sf/memory-extractor.ts | SF Workflow | Memory and context extraction from state |
| sf/structured-data-formatter.ts | SF Workflow | Structured output formatting |
| sf/export-html.ts | SF Workflow | HTML export of milestone reports |
| sf/reports.ts | SF Workflow | Report generation and summaries |
| sf/notifications.ts | SF Workflow | User notification and messaging |
| sf/triage-ui.ts | SF Workflow | Triage interface for issue categorization |
| sf/guided-flow.ts | SF Workflow | User-guided workflow orchestration |
| sf/env-utils.ts | SF Workflow | Environment variable utilities |
| sf/git-constants.ts | SF Workflow | Git-related constants and paths |
| sf/milestone-id-utils.ts | SF Workflow | Milestone ID generation and parsing |
| sf/resource-version.ts | SF Workflow | Resource versioning helpers |
| sf/atomic-write.ts | SF Workflow | Atomic file write operations |
| sf/captures.ts | SF Workflow | Artifact capture and storage |
| sf/changelog.ts | SF Workflow | Changelog generation |
| sf/claude-import.ts | SF Workflow | Claude API/resource importing |
| sf/collision-diagnostics.ts | Doctor/Diagnostics | Collision detection and diagnostics |
| sf/prompt-loader.ts | SF Workflow | Prompt template loading |
| sf/file-watcher.ts | SF Workflow | File system change monitoring |
| sf/parallel-eligibility.ts | SF Workflow | Parallel execution eligibility checks |
| sf/plugin-importer.ts | SF Workflow, Extensions | Custom plugin/extension importing |
| sf/verification-gate.ts | SF Workflow | Pre-execution verification checks |
| sf/preference-models.ts | Config, Model System | Model preference configuration |
| sf/preferences-skills.ts | Config, Skills | Skill preference configuration |
| sf/post-unit-hooks.ts | SF Workflow | Post-unit execution hooks |
| sf/skill-telemetry.ts | Skills | Skill usage and performance telemetry |
| sf/bootstrap/* | SF Workflow, Loader/Bootstrap | Extension initialization and hook registration |
| sf/auto/* | Auto Engine | Auto-execution engine components |
| sf/commands/* | Commands | Command routing and handling |
| sf/templates/* | SF Workflow | Output templates and formatters |
| sf/prompts/* | SF Workflow | System prompts and instructions |
| sf/workflow-templates/* | SF Workflow | Workflow starter templates and registry |
| sf/skills/* | Skills | Integrated skill configurations |
| sf/migrate/* | Migration | Data migration and upgrade tools |
### Other Extensions
@ -658,7 +658,7 @@
| react-best-practices/ | Skills | React development patterns (62 files) |
| userinterface-wiki/ | Skills | UI/UX guidelines and component reference (155 files) |
| create-skill/ | Skills | Skill creation scaffolding and templates (25 files) |
| create-gsd-extension/ | Skills, Extensions | SF extension scaffolding (22 files) |
| create-sf-extension/ | Skills, Extensions | SF extension scaffolding (22 files) |
| code-optimizer/ | Skills | Performance optimization techniques (16 files) |
| agent-browser/ | Skills, Browser Tools | Browser automation guidance (11 files) |
| github-workflows/ | Skills | GitHub Actions workflow patterns (10 files) |
@ -684,64 +684,64 @@
|------|-----------------|-------------|
| web/app/layout.tsx | Web UI | Root Next.js layout with theme provider and font |
| web/app/page.tsx | Web UI | Entry page loading GSDAppShell |
| web/components/gsd/app-shell.tsx | Web UI | Main app shell — sidebar, panels, terminal, commands |
| web/components/gsd/sidebar.tsx | Web UI | Multi-panel sidebar with milestone explorer |
| web/components/gsd/status-bar.tsx | Web UI | Status bar with workspace state and metrics |
| web/components/sf/app-shell.tsx | Web UI | Main app shell — sidebar, panels, terminal, commands |
| web/components/sf/sidebar.tsx | Web UI | Multi-panel sidebar with milestone explorer |
| web/components/sf/status-bar.tsx | Web UI | Status bar with workspace state and metrics |
### Main Views
| File | System Label(s) | Description |
|------|-----------------|-------------|
| web/components/gsd/dashboard.tsx | Web UI | Dashboard with workflow actions and metrics |
| web/components/gsd/chat-mode.tsx | Web UI | Chat interface for agent interaction |
| web/components/gsd/projects-view.tsx | Web UI | Project browser and selector |
| web/components/gsd/files-view.tsx | Web UI | File browser and explorer |
| web/components/gsd/activity-view.tsx | Web UI | Activity log and history view |
| web/components/gsd/roadmap.tsx | Web UI, SF Workflow | Milestone roadmap visualization |
| web/components/gsd/visualizer-view.tsx | Web UI, Doctor/Diagnostics | Workflow visualization |
| web/components/gsd/project-welcome.tsx | Web UI | Welcome screen for new projects |
| web/components/gsd/knowledge-captures-panel.tsx | Web UI | Knowledge and capture management |
| web/components/sf/dashboard.tsx | Web UI | Dashboard with workflow actions and metrics |
| web/components/sf/chat-mode.tsx | Web UI | Chat interface for agent interaction |
| web/components/sf/projects-view.tsx | Web UI | Project browser and selector |
| web/components/sf/files-view.tsx | Web UI | File browser and explorer |
| web/components/sf/activity-view.tsx | Web UI | Activity log and history view |
| web/components/sf/roadmap.tsx | Web UI, SF Workflow | Milestone roadmap visualization |
| web/components/sf/visualizer-view.tsx | Web UI, Doctor/Diagnostics | Workflow visualization |
| web/components/sf/project-welcome.tsx | Web UI | Welcome screen for new projects |
| web/components/sf/knowledge-captures-panel.tsx | Web UI | Knowledge and capture management |
### Terminal
| File | System Label(s) | Description |
|------|-----------------|-------------|
| web/components/gsd/terminal.tsx | Web UI | Terminal widget with input mode handling |
| web/components/gsd/shell-terminal.tsx | Web UI | Shell terminal with PTY integration |
| web/components/gsd/main-session-terminal.tsx | Web UI | Main session terminal display |
| web/components/gsd/dual-terminal.tsx | Web UI | Side-by-side terminal layout |
| web/components/sf/terminal.tsx | Web UI | Terminal widget with input mode handling |
| web/components/sf/shell-terminal.tsx | Web UI | Shell terminal with PTY integration |
| web/components/sf/main-session-terminal.tsx | Web UI | Main session terminal display |
| web/components/sf/dual-terminal.tsx | Web UI | Side-by-side terminal layout |
### Commands & Dialogs
| File | System Label(s) | Description |
|------|-----------------|-------------|
| web/components/gsd/command-surface.tsx | Web UI, Commands | Command palette and slash command dispatcher |
| web/components/gsd/remaining-command-panels.tsx | Web UI, Commands | History, undo, export, cleanup panels |
| web/components/gsd/diagnostics-panels.tsx | Web UI, Doctor/Diagnostics | Doctor, forensics, skill health panels |
| web/components/gsd/settings-panels.tsx | Web UI, Config | Settings and preferences panels |
| web/components/gsd/guided-dialog.tsx | Web UI | Generic guided dialog component |
| web/components/gsd/update-banner.tsx | Web UI | Update notification banner |
| web/components/gsd/scope-badge.tsx | Web UI | Scope badge indicator |
| web/components/gsd/loading-skeletons.tsx | Web UI | Loading skeleton placeholders |
| web/components/gsd/code-editor.tsx | Web UI | Code editor display component |
| web/components/gsd/file-content-viewer.tsx | Web UI | File content viewer and previewer |
| web/components/gsd/focused-panel.tsx | Web UI | Focused panel layout component |
| web/components/sf/command-surface.tsx | Web UI, Commands | Command palette and slash command dispatcher |
| web/components/sf/remaining-command-panels.tsx | Web UI, Commands | History, undo, export, cleanup panels |
| web/components/sf/diagnostics-panels.tsx | Web UI, Doctor/Diagnostics | Doctor, forensics, skill health panels |
| web/components/sf/settings-panels.tsx | Web UI, Config | Settings and preferences panels |
| web/components/sf/guided-dialog.tsx | Web UI | Generic guided dialog component |
| web/components/sf/update-banner.tsx | Web UI | Update notification banner |
| web/components/sf/scope-badge.tsx | Web UI | Scope badge indicator |
| web/components/sf/loading-skeletons.tsx | Web UI | Loading skeleton placeholders |
| web/components/sf/code-editor.tsx | Web UI | Code editor display component |
| web/components/sf/file-content-viewer.tsx | Web UI | File content viewer and previewer |
| web/components/sf/focused-panel.tsx | Web UI | Focused panel layout component |
### Onboarding
| File | System Label(s) | Description |
|------|-----------------|-------------|
| web/components/gsd/onboarding-gate.tsx | Web UI, Onboarding | Gate and orchestration for onboarding flow |
| web/components/gsd/onboarding/step-welcome.tsx | Web UI, Onboarding | Welcome step |
| web/components/gsd/onboarding/step-mode.tsx | Web UI, Onboarding | User mode selection step |
| web/components/gsd/onboarding/step-provider.tsx | Web UI, Onboarding | LLM provider selection step |
| web/components/gsd/onboarding/step-authenticate.tsx | Web UI, Onboarding, Auth/OAuth | Authentication step |
| web/components/gsd/onboarding/step-dev-root.tsx | Web UI, Onboarding | Dev root directory selection step |
| web/components/gsd/onboarding/step-project.tsx | Web UI, Onboarding | Project selection step |
| web/components/gsd/onboarding/step-remote.tsx | Web UI, Onboarding | Remote configuration step |
| web/components/gsd/onboarding/step-optional.tsx | Web UI, Onboarding | Optional settings step |
| web/components/gsd/onboarding/step-ready.tsx | Web UI, Onboarding | Ready confirmation step |
| web/components/gsd/onboarding/wizard-stepper.tsx | Web UI, Onboarding | Stepper progress indicator |
| web/components/sf/onboarding-gate.tsx | Web UI, Onboarding | Gate and orchestration for onboarding flow |
| web/components/sf/onboarding/step-welcome.tsx | Web UI, Onboarding | Welcome step |
| web/components/sf/onboarding/step-mode.tsx | Web UI, Onboarding | User mode selection step |
| web/components/sf/onboarding/step-provider.tsx | Web UI, Onboarding | LLM provider selection step |
| web/components/sf/onboarding/step-authenticate.tsx | Web UI, Onboarding, Auth/OAuth | Authentication step |
| web/components/sf/onboarding/step-dev-root.tsx | Web UI, Onboarding | Dev root directory selection step |
| web/components/sf/onboarding/step-project.tsx | Web UI, Onboarding | Project selection step |
| web/components/sf/onboarding/step-remote.tsx | Web UI, Onboarding | Remote configuration step |
| web/components/sf/onboarding/step-optional.tsx | Web UI, Onboarding | Optional settings step |
| web/components/sf/onboarding/step-ready.tsx | Web UI, Onboarding | Ready confirmation step |
| web/components/sf/onboarding/wizard-stepper.tsx | Web UI, Onboarding | Stepper progress indicator |
### API Routes
@ -792,7 +792,7 @@
| File | System Label(s) | Description |
|------|-----------------|-------------|
| web/lib/auth.ts | Auth/OAuth | Client-side auth token management from URL fragment |
| web/lib/gsd-workspace-store.tsx | State Machine | Global workspace state store with external store |
| web/lib/sf-workspace-store.tsx | State Machine | Global workspace state store with external store |
| web/lib/project-store-manager.tsx | State Machine | Multi-project store manager with SSE lifecycle |
| web/lib/shutdown-gate.ts | State Machine | Graceful shutdown coordination |
| web/lib/browser-slash-command-dispatch.ts | Commands | Slash command dispatch |
@ -827,8 +827,8 @@
| File | System Label(s) | Description |
|------|-----------------|-------------|
| vscode-extension/src/extension.ts | VS Code Extension | Extension activation, client management, command registration |
| vscode-extension/src/gsd-client.ts | VS Code Extension, MCP Server/Client | RPC client for SF agent communication |
| vscode-extension/src/chat-participant.ts | VS Code Extension | Chat participant for @gsd command |
| vscode-extension/src/sf-client.ts | VS Code Extension, MCP Server/Client | RPC client for SF agent communication |
| vscode-extension/src/chat-participant.ts | VS Code Extension | Chat participant for @sf command |
| vscode-extension/src/sidebar.ts | VS Code Extension | Sidebar webview provider with status display |
---
@ -865,7 +865,7 @@
| native/crates/engine/src/ps.rs | Native/Rust Tools | Cross-platform process tree management |
| native/crates/engine/src/clipboard.rs | Native/Rust Tools | Clipboard read/write for text and images |
| native/crates/engine/src/json_parse.rs | Text Processing, Native/Rust Tools | Streaming JSON parser with partial recovery |
| native/crates/engine/src/gsd_parser.rs | SF Workflow, Native/Rust Tools | .gsd/ directory file parser (markdown, frontmatter) |
| native/crates/engine/src/gsd_parser.rs | SF Workflow, Native/Rust Tools | .sf/ directory file parser (markdown, frontmatter) |
| native/crates/engine/src/ttsr.rs | TTSR, Native/Rust Tools | TTSR regex engine with compiled RegexSet |
| native/crates/engine/src/stream_process.rs | Text Processing, Native/Rust Tools | Bash stream processor (UTF-8, ANSI strip, binary) |
| native/crates/engine/src/xxhash.rs | Native/Rust Tools | xxHash32 for hashline edit tool |
@ -948,10 +948,10 @@
| scripts/check-skill-references.mjs | Build System, Skills | Skill reference validator |
| scripts/preview-dashboard.ts | Web Mode | Dashboard preview server |
| scripts/ci_monitor.cjs | Build System | CI monitoring dashboard |
| scripts/recover-gsd-1364.sh | Build System, Migration | Recovery script for issue #1364 |
| scripts/recover-gsd-1364.ps1 | Build System, Migration | Recovery script for issue #1364 (PowerShell) |
| scripts/recover-gsd-1668.sh | Build System, Migration | Recovery script for issue #1668 |
| scripts/recover-gsd-1668.ps1 | Build System, Migration | Recovery script for issue #1668 (PowerShell) |
| scripts/recover-sf-1364.sh | Build System, Migration | Recovery script for issue #1364 |
| scripts/recover-sf-1364.ps1 | Build System, Migration | Recovery script for issue #1364 (PowerShell) |
| scripts/recover-sf-1668.sh | Build System, Migration | Recovery script for issue #1668 |
| scripts/recover-sf-1668.ps1 | Build System, Migration | Recovery script for issue #1668 (PowerShell) |
---
@ -967,44 +967,44 @@ Quick lookup: which files are part of each system?
| **AST** | native/crates/ast/*, packages/native/src/ast/ |
| **Async Jobs** | src/resources/extensions/async-jobs/* |
| **Auth / OAuth** | pi-ai/src/utils/oauth/*, src/web/web-auth-storage.ts, core/auth-storage.ts, src/pi-migration.ts, aws-auth/index.ts, web/lib/auth.ts |
| **Auto Engine** | src/resources/extensions/gsd/auto*.ts, gsd/auto-loop.ts, gsd/auto-supervisor.ts, gsd/unit-runtime.ts |
| **Auto Engine** | src/resources/extensions/sf/auto*.ts, sf/auto-loop.ts, sf/auto-supervisor.ts, sf/unit-runtime.ts |
| **Bg Shell** | src/resources/extensions/bg-shell/* |
| **Browser Tools** | src/resources/extensions/browser-tools/* |
| **Build System** | scripts/*, native/crates/engine/build.rs |
| **CLI** | src/cli.ts, src/cli-web-branch.ts, src/help-text.ts, src/update*.ts, pi-coding-agent/src/cli.ts, src/worktree-cli.ts |
| **CMux** | src/resources/extensions/cmux/index.ts |
| **Commands** | gsd/commands*.ts, gsd/exit-command.ts, gsd/undo.ts, gsd/kill.ts, pi-coding-agent/src/core/slash-commands.ts |
| **Commands** | sf/commands*.ts, sf/exit-command.ts, sf/undo.ts, sf/kill.ts, pi-coding-agent/src/core/slash-commands.ts |
| **Compaction** | pi-coding-agent/src/core/compaction*.ts, core/compaction/* |
| **Config** | src/app-paths.ts, src/models-resolver.ts, src/remote-questions-config.ts, src/wizard.ts, core/defaults.ts, core/constants.ts, config.ts |
| **Context7** | src/resources/extensions/context7/index.ts |
| **Doctor / Diagnostics** | gsd/doctor*.ts, gsd/collision-diagnostics.ts, core/diagnostics.ts, web/lib/diagnostics-types.ts, web/app/api/doctor/*, forensics/* |
| **Event System** | pi-coding-agent/src/core/event-bus.ts, gsd/auto-observability.ts |
| **Doctor / Diagnostics** | sf/doctor*.ts, sf/collision-diagnostics.ts, core/diagnostics.ts, web/lib/diagnostics-types.ts, web/app/api/doctor/*, forensics/* |
| **Event System** | pi-coding-agent/src/core/event-bus.ts, sf/auto-observability.ts |
| **Extension Registry** | src/extension-discovery.ts, src/extension-registry.ts, src/bundled-extension-paths.ts |
| **Extensions** | pi-coding-agent/src/core/extensions/*, src/resource-loader.ts |
| **File Search** | native/crates/engine/src/grep.rs, glob.rs, fd.rs, fs_cache.rs, packages/native/src/grep/*, fd/*, core/tools/grep.ts, find.ts |
| **SF Workflow** | src/resources/extensions/gsd/* (non-auto), gsd/reports.ts, gsd/notifications.ts, gsd/prompts/*, gsd/workflow-templates/* |
| **SF Workflow** | src/resources/extensions/sf/* (non-auto), sf/reports.ts, sf/notifications.ts, sf/prompts/*, sf/workflow-templates/* |
| **Google Search** | src/resources/extensions/google-search/index.ts |
| **Headless Mode** | src/headless*.ts |
| **Image Processing** | native/crates/engine/src/image.rs, packages/native/src/image/*, utils/image-*.ts, web/lib/image-utils.ts |
| **Integration Tests** | tests/**/* |
| **Loader / Bootstrap** | src/loader.ts, src/resource-loader.ts, src/tool-bootstrap.ts, src/bundled-resource-path.ts, gsd/bootstrap/* |
| **Loader / Bootstrap** | src/loader.ts, src/resource-loader.ts, src/tool-bootstrap.ts, src/bundled-resource-path.ts, sf/bootstrap/* |
| **LSP** | pi-coding-agent/src/core/lsp/* |
| **Mac Tools** | src/resources/extensions/mac-tools/* |
| **MCP Server/Client** | src/mcp-server.ts, src/resources/extensions/mcp-client/index.ts, vscode-extension/src/gsd-client.ts, modes/rpc/* |
| **MCP Server/Client** | src/mcp-server.ts, src/resources/extensions/mcp-client/index.ts, vscode-extension/src/sf-client.ts, modes/rpc/* |
| **Memory Extension** | pi-coding-agent/src/resources/extensions/memory/* |
| **Migration** | gsd/migrate/*, src/pi-migration.ts, pi-coding-agent/src/migrations.ts, scripts/recover-*.sh |
| **Migration** | sf/migrate/*, src/pi-migration.ts, pi-coding-agent/src/migrations.ts, scripts/recover-*.sh |
| **Modes** | pi-coding-agent/src/modes/* |
| **Model System** | pi-coding-agent/src/core/model-*.ts, pi-ai/src/models*.ts, pi-ai/src/api-registry.ts, gsd/model-router.ts |
| **Model System** | pi-coding-agent/src/core/model-*.ts, pi-ai/src/models*.ts, pi-ai/src/api-registry.ts, sf/model-router.ts |
| **Native / Rust Tools** | native/crates/engine/src/* |
| **Node.js Bindings** | packages/native/src/* |
| **Onboarding** | src/onboarding.ts, src/wizard.ts, web/components/gsd/onboarding/*, web/app/api/onboarding/* |
| **Onboarding** | src/onboarding.ts, src/wizard.ts, web/components/sf/onboarding/*, web/app/api/onboarding/* |
| **Permissions** | core/extensions/project-trust.ts, core/auth-storage.ts |
| **Remote Questions** | src/resources/extensions/remote-questions/* |
| **Search the Web** | src/resources/extensions/search-the-web/* |
| **Session Management** | pi-coding-agent/src/core/session-manager.ts, core/settings-manager.ts, web/app/api/session/* |
| **Skills** | src/resources/skills/*, gsd/skill-telemetry.ts, gsd/preferences-skills.ts, core/skills.ts |
| **Skills** | src/resources/skills/*, sf/skill-telemetry.ts, sf/preferences-skills.ts, core/skills.ts |
| **Slash Commands** | src/resources/extensions/slash-commands/* |
| **State Machine** | gsd/state.ts, gsd/history.ts, gsd/json-persistence.ts, gsd/memory-store.ts, gsd/reactive-graph.ts, core/agent-session.ts, web/lib/gsd-workspace-store.tsx |
| **State Machine** | sf/state.ts, sf/history.ts, sf/json-persistence.ts, sf/memory-store.ts, sf/reactive-graph.ts, core/agent-session.ts, web/lib/sf-workspace-store.tsx |
| **Studio App** | studio/* |
| **Subagent** | src/resources/extensions/subagent/*, src/resources/agents/* |
| **Syntax Highlighting** | native/crates/engine/src/highlight.rs, packages/native/src/highlight/* |
@ -1017,4 +1017,4 @@ Quick lookup: which files are part of each system?
| **VS Code Extension** | vscode-extension/src/* |
| **Web Mode** | src/web/*.ts, src/web-mode.ts |
| **Web UI** | web/app/*.tsx, web/components/*, web/hooks/*, web/lib/* |
| **Worktree** | src/worktree-cli.ts, src/worktree-name-gen.ts, gsd/worktree*.ts, tests/repro-worktree-bug/* |
| **Worktree** | src/worktree-cli.ts, src/worktree-name-gen.ts, sf/worktree*.ts, tests/repro-worktree-bug/* |

92
docs/dev/PRD-branchless-worktree-architecture.md
View file

@ -13,7 +13,7 @@ SF's auto-mode is unreliable. Users experience:
1. **Infinite loop detection failures** — the agent writes planning artifacts on slice branches that become invisible after branch switching, causing `verifyExpectedArtifact()` to fail repeatedly. Auto-mode burns budget retrying the same unit 3-6 times before hard-stopping. This is the #1 user complaint.
2. **State corruption across branches** — `.gsd/` planning artifacts (roadmaps, plans, decisions) are gitignored but branch-specific. Multiple branches sharing a single `.gsd/` directory clobber each other's state. Users see wrong milestones marked complete, wrong roadmaps loaded, and auto-mode starting from the wrong phase.
2. **State corruption across branches** — `.sf/` planning artifacts (roadmaps, plans, decisions) are gitignored but branch-specific. Multiple branches sharing a single `.sf/` directory clobber each other's state. Users see wrong milestones marked complete, wrong roadmaps loaded, and auto-mode starting from the wrong phase.
3. **Excessive complexity** — 770+ lines of merge, conflict resolution, branch switching, and self-healing code exist solely to manage slice branches inside worktrees. This code has required 15+ bug fixes across versions and remains the primary source of auto-mode failures.
@ -28,10 +28,10 @@ Auto-mode uses git worktrees for isolation and sequential commits for history. N
| Criterion | Measurement |
|-----------|-------------|
| Zero loop detection failures from branch visibility | No `verifyExpectedArtifact()` failures caused by branch mismatch in 50 consecutive auto-mode runs |
| Zero `.gsd/` state corruption | Manual worktrees created via `git worktree add` have correct `.gsd/` state without any SF-specific initialization |
| Zero `.sf/` state corruption | Manual worktrees created via `git worktree add` have correct `.sf/` state without any SF-specific initialization |
| Code deletion | Net removal of ≥500 lines of merge/conflict/branch-switching code |
| Test simplification | Removal or simplification of ≥6 merge-specific test files |
| Backwards compatibility | Existing projects with `gsd/M001/S01` slice branches continue to work (read-only; new work uses new model) |
| Backwards compatibility | Existing projects with `sf/M001/S01` slice branches continue to work (read-only; new work uses new model) |
| No new git primitives | The implementation uses only: worktrees, commits, squash-merge. No new branch types, merge strategies, or conflict resolution. |
## Non-Goals
@ -47,10 +47,10 @@ Auto-mode uses git worktrees for isolation and sequential commits for history. N
```
main
└─ milestone/M001 (worktree at .gsd/worktrees/M001/)
├─ gsd/M001/S01 (slice branch — code + .gsd/ artifacts)
└─ milestone/M001 (worktree at .sf/worktrees/M001/)
├─ sf/M001/S01 (slice branch — code + .sf/ artifacts)
│ └── merge --no-ff → milestone/M001
├─ gsd/M001/S02
├─ sf/M001/S02
│ └── merge --no-ff → milestone/M001
└── squash merge → main
```
@ -74,11 +74,11 @@ Agent writes file → on slice branch → handleAgentEnd → auto-commit on slic
| `worktree.ts` | ~40 lines | Slice branch delegates |
| 11 test files | ~2000 lines | Merge/branch/worktree test coverage |
### `.gsd/` Tracking (Current — Contradictory)
### `.sf/` Tracking (Current — Contradictory)
- `.gitignore` line 52: `.gsd/` — ignores everything
- `.gitignore` line 52: `.sf/` — ignores everything
- `smartStage()` lines 338-349: force-adds `SF_DURABLE_PATHS` — tracks milestones/, DECISIONS.md, PROJECT.md, REQUIREMENTS.md, QUEUE.md
- Result: `.gsd/milestones/` is partially tracked on some branches, fully ignored on others. The code fights the config.
- Result: `.sf/milestones/` is partially tracked on some branches, fully ignored on others. The code fights the config.
## Proposed Architecture
@ -86,7 +86,7 @@ Agent writes file → on slice branch → handleAgentEnd → auto-commit on slic
```
main
└─ milestone/M001 (worktree at .gsd/worktrees/M001/)
└─ milestone/M001 (worktree at .sf/worktrees/M001/)
│
commit: feat(M001): context + roadmap
commit: feat(M001/S01): research
@ -112,31 +112,31 @@ Agent writes file → on milestone branch → handleAgentEnd → auto-commit on
→ verifyExpectedArtifact → FILE FOUND (same branch) → persist completion → next dispatch
```
### `.gsd/` Tracking (Proposed — Coherent)
### `.sf/` Tracking (Proposed — Coherent)
**Tracked (travels with branch):**
```
.gsd/milestones/**/*.md (except CONTINUE markers)
.gsd/milestones/**/*.json (META.json integration records)
.gsd/PROJECT.md
.gsd/DECISIONS.md
.gsd/REQUIREMENTS.md
.gsd/QUEUE.md
.sf/milestones/**/*.md (except CONTINUE markers)
.sf/milestones/**/*.json (META.json integration records)
.sf/PROJECT.md
.sf/DECISIONS.md
.sf/REQUIREMENTS.md
.sf/QUEUE.md
```
**Gitignored (ephemeral):**
```
.gsd/auto.lock
.gsd/completed-units.json
.gsd/STATE.md
.gsd/metrics.json
.gsd/gsd.db
.gsd/activity/
.gsd/runtime/
.gsd/worktrees/
.gsd/DISCUSSION-MANIFEST.json
.gsd/milestones/**/*-CONTINUE.md
.gsd/milestones/**/continue.md
.sf/auto.lock
.sf/completed-units.json
.sf/STATE.md
.sf/metrics.json
.sf/sf.db
.sf/activity/
.sf/runtime/
.sf/worktrees/
.sf/DISCUSSION-MANIFEST.json
.sf/milestones/**/*-CONTINUE.md
.sf/milestones/**/continue.md
```
### Why This Works
@ -144,7 +144,7 @@ Agent writes file → on milestone branch → handleAgentEnd → auto-commit on
| Problem | How It's Solved |
|---------|----------------|
| Artifact invisibility after branch switch | No branch switching. Artifacts commit on the one branch. |
| `.gsd/` state clobbering | Artifacts tracked in git. Each branch carries its own `.gsd/`. `git worktree add` and `git checkout` give correct state. |
| `.sf/` state clobbering | Artifacts tracked in git. Each branch carries its own `.sf/`. `git worktree add` and `git checkout` give correct state. |
| Merge conflict complexity | No merges within a worktree. Only merge is milestone→main (squash). |
| Manual worktree initialization | Tracked artifacts are checked out with the branch. No SF-specific bootstrap needed. |
| Dual isolation mode maintenance | Single mode: worktree. Branch-mode (`git.isolation: "branch"`) deprecated. |
@ -156,24 +156,24 @@ Agent writes file → on milestone branch → handleAgentEnd → auto-commit on
**Goal:** Planning artifacts are tracked in git. `.gitignore` reflects reality.
1. Update `.gitignore`:
- Remove blanket `.gsd/` ignore
- Remove blanket `.sf/` ignore
- Add explicit runtime-only ignores (see proposed list above)
2. Force-add existing planning artifacts on current branch:
```
git add --force .gsd/milestones/ .gsd/PROJECT.md .gsd/DECISIONS.md .gsd/REQUIREMENTS.md .gsd/QUEUE.md
git add --force .sf/milestones/ .sf/PROJECT.md .sf/DECISIONS.md .sf/REQUIREMENTS.md .sf/QUEUE.md
```
3. Ensure runtime files are NOT tracked:
```
git rm --cached -r .gsd/runtime/ .gsd/activity/ .gsd/STATE.md .gsd/metrics.json .gsd/completed-units.json .gsd/auto.lock
git rm --cached -r .sf/runtime/ .sf/activity/ .sf/STATE.md .sf/metrics.json .sf/completed-units.json .sf/auto.lock
```
4. Update README suggested `.gitignore` section
5. Remove `smartStage()` force-add of `SF_DURABLE_PATHS` — no longer needed since `.gitignore` doesn't block them
**Verification:** `git status` shows planning artifacts tracked, runtime files untracked. `git worktree add` on a new worktree has correct `.gsd/milestones/` state.
**Verification:** `git status` shows planning artifacts tracked, runtime files untracked. `git worktree add` on a new worktree has correct `.sf/milestones/` state.
### Phase 2: Remove Slice Branch Creation + Switching
@ -219,7 +219,7 @@ The function becomes:
7. Optional: `git push`
8. `removeWorktree()` + `git branch -D milestone/<MID>`
No conflict categorization. No runtime file stripping (runtime files are gitignored, not in the merge). No `.gsd/` special handling.
No conflict categorization. No runtime file stripping (runtime files are gitignored, not in the merge). No `.sf/` special handling.
If squash-merge conflicts (parallel milestone edge case): stop auto-mode with clear error, user resolves manually or SF dispatches a one-time resolution session.
@ -238,8 +238,8 @@ If squash-merge conflicts (parallel milestone edge case): stop auto-mode with cl
2. Add new tests:
- Branchless worktree lifecycle: create → commit → commit → squash-merge → cleanup
- `.gsd/` tracking: planning artifacts tracked, runtime files ignored
- Manual worktree: `git worktree add` has correct `.gsd/` state
- `.sf/` tracking: planning artifacts tracked, runtime files ignored
- Manual worktree: `git worktree add` has correct `.sf/` state
- Crash recovery: dirty state on milestone branch, restart, auto-commit, continue
3. Remove merge-specific doctor checks or simplify:
@ -254,7 +254,7 @@ If squash-merge conflicts (parallel milestone edge case): stop auto-mode with cl
**Goal:** Existing projects with slice branches continue to work.
1. State derivation (`deriveState()`) continues to read `gsd/M001/S01` branch naming for legacy detection
1. State derivation (`deriveState()`) continues to read `sf/M001/S01` branch naming for legacy detection
2. On first run after upgrade:
- Detect existing slice branches
- Notify user: "SF no longer creates slice branches. Existing branches are preserved but new work commits directly to the milestone branch."
@ -265,7 +265,7 @@ If squash-merge conflicts (parallel milestone edge case): stop auto-mode with cl
- `git.isolation: "branch"` → warning, treated as worktree
- Remove preference UI for isolation mode
**Verification:** Open a project with existing `gsd/M001/S01` branches. SF reads state correctly, new work commits on milestone branch without slice branches.
**Verification:** Open a project with existing `sf/M001/S01` branches. SF reads state correctly, new work commits on milestone branch without slice branches.
## Stress Test Results
@ -286,7 +286,7 @@ Validated by three independent models:
- Confirmed `smartStage()` force-add already implements tracked-artifact intent
- Confirmed `resolveMainWorktreeRoot` (PR #487) contradicts this architecture
- Confirmed `.gsd/milestones/` partially tracked on `main` despite `.gitignore`
- Confirmed `.sf/milestones/` partially tracked on `main` despite `.gitignore`
- Verdict: **Model is sound. Removes only accidental complexity.**
### GPT-5.4 (Codex) — Dissenting Opinion
@ -298,7 +298,7 @@ Codex agreed on tracked artifacts and worktree-per-milestone, but pushed back on
| Crash recovery for orphaned slice branches disappears | The failure mode (orphaned branch needing merge) is caused by slice branches. Removing branches removes the failure. Sequential commits on one branch need no orphan recovery. |
| Concurrent edits to shared root docs (DECISIONS.md) from two terminals | Standard content conflict at squash-merge time. Not caused by or solved by slice branches. |
| Continuous integration via slice→milestone merges | In sequential single-user work, there's nothing to integrate against within the worktree. Pre-flight rebase before squash-merge is more direct. |
| Need a replacement slice-boundary primitive | Accepted: conventional commit tags (`feat(M001/S01):`) + optional git tags (`gsd/M001/S01-complete`) serve as boundaries. |
| Need a replacement slice-boundary primitive | Accepted: conventional commit tags (`feat(M001/S01):`) + optional git tags (`sf/M001/S01-complete`) serve as boundaries. |
Codex's analysis confirms the tracked-artifact approach but recommends treating branchless as a deliberate redesign with explicit replacement primitives, not a casual deletion.
@ -308,10 +308,10 @@ Scenario: M001 and M002 both modify `src/auth.ts`. M001 squash-merges first.
Resolution: Before M002 squash-merges, rebase onto updated `main`:
```
cd .gsd/worktrees/M002
cd .sf/worktrees/M002
git fetch origin main
git rebase main
# Resolve any conflicts (code-only, never .gsd/)
# Resolve any conflicts (code-only, never .sf/)
# Then squash-merge
```
@ -340,7 +340,7 @@ Resolution: Worktree is on `milestone/M001` branch, independent of `main`. Manua
|--------|-------|
| Merge/conflict/branch code | 770+ lines across 4 files |
| Merge-related test files | 11 files |
| Branch types | 4 (main, milestone/*, gsd/*/*, worktree/*) |
| Branch types | 4 (main, milestone/*, sf/*/*, worktree/*) |
| Merge strategies | 3 (--no-ff, --squash, conflict resolution) |
| Dispatch unit types with merge logic | 2 (complete-slice, fix-merge) |
| Isolation modes | 2 (branch, worktree) |
@ -370,14 +370,14 @@ Resolution: Worktree is on `milestone/M001` branch, independent of `main`. Manua
## Dependencies
- **M001 (Memory Database):** The SQLite database (`gsd.db`) must remain gitignored. The M001/S02 importer layer rebuilds it from tracked markdown. This PRD's `.gitignore` update explicitly ignores `gsd.db`.
- **M001 (Memory Database):** The SQLite database (`sf.db`) must remain gitignored. The M001/S02 importer layer rebuilds it from tracked markdown. This PRD's `.gitignore` update explicitly ignores `sf.db`.
- **PR #487:** Must be closed. The `resolveMainWorktreeRoot` approach (sharing `.gsd/` across worktrees) contradicts tracked-artifact architecture.
- **PR #487:** Must be closed. The `resolveMainWorktreeRoot` approach (sharing `.sf/` across worktrees) contradicts tracked-artifact architecture.
## Open Questions
1. **Squash vs `--no-ff` for milestone→main merge?** Squash gives clean history on `main` but loses bisect granularity. `--no-ff` preserves granular commits but clutters `main`. Current proposal: squash (matching existing behavior), with option to preserve milestone branch for debugging.
2. **Should `worktrees/` move outside `.gsd/`?** Having worktrees inside `.gsd/` creates a nesting-doll pattern (worktree contains `.gsd/` which is inside `.gsd/worktrees/`). Relocating to `.gsd-worktrees/` or `~/.gsd/worktrees/<repo-hash>/` is cleaner but changes the filesystem layout. Recommendation: defer, address separately if it causes issues.
2. **Should `worktrees/` move outside `.sf/`?** Having worktrees inside `.sf/` creates a nesting-doll pattern (worktree contains `.sf/` which is inside `.sf/worktrees/`). Relocating to `.sf-worktrees/` or `~/.sf/worktrees/<repo-hash>/` is cleaner but changes the filesystem layout. Recommendation: defer, address separately if it causes issues.
3. **Pre-flight rebase automation?** Before milestone→main squash-merge, should SF automatically `git rebase main`? Gemini recommends yes. Risk: rebase can fail with conflicts, adding a code path. Recommendation: implement as a doctor check ("milestone branch is behind main by N commits") with manual resolution, automate later if needed.

34
docs/dev/PRD-pi-clean-seam-refactor.md
View file

@ -25,9 +25,9 @@ SF's code is clearly separated from pi's code at the module system level. The ve
| Criterion | Measurement |
|-----------|-------------|
| Zero SF business logic in vendored pi packages | `pi-coding-agent/src/` contains no files that import from `@gsd/` packages (except the extension system's bundled module map) |
| Zero SF business logic in vendored pi packages | `pi-coding-agent/src/` contains no files that import from `@sf/` packages (except the extension system's bundled module map) |
| Module boundary is compiler-enforced | TypeScript `paths` config or package `exports` prevents pi packages from importing SF packages |
| Applying a pi-mono update is scoped | Updating pi packages produces type errors only in `@gsd/agent-core` and `@gsd/agent-modes` — no changes required in pi package source files |
| Applying a pi-mono update is scoped | Updating pi packages produces type errors only in `@sf/agent-core` and `@sf/agent-modes` — no changes required in pi package source files |
| Install experience is unchanged | `npm install -g sf-run@latest` produces an identical binary from the user's perspective |
| Existing extensions continue to work | All built-in SF extensions load and execute without modification |
| Build time does not regress significantly | Full build completes within 120% of current baseline |
@ -43,14 +43,14 @@ SF's code is clearly separated from pi's code at the module system level. The ve
## Stakeholders
- **Maintainers applying pi updates** — primary beneficiary; this work directly reduces their update burden
- **Extension authors** — must not be broken; the extension API surface stays in `@gsd/pi-coding-agent`
- **Extension authors** — must not be broken; the extension API surface stays in `@sf/pi-coding-agent`
- **End users** — not impacted; the refactor is entirely internal
## Requirements
### R1 — New package: `@gsd/agent-core`
### R1 — New package: `@sf/agent-core`
A new workspace package at `packages/gsd-agent-core/` that owns all SF session orchestration logic. It depends on `@gsd/pi-coding-agent`, `@gsd/pi-agent-core`, and `@gsd/pi-ai`. Nothing in the vendored pi packages depends on it.
A new workspace package at `packages/sf-agent-core/` that owns all SF session orchestration logic. It depends on `@sf/pi-coding-agent`, `@sf/pi-agent-core`, and `@sf/pi-ai`. Nothing in the vendored pi packages depends on it.
Must contain:
- `agent-session.ts` and all `AgentSession` types
@ -66,9 +66,9 @@ Must contain:
- `artifact-manager.ts`, `blob-store.ts`
- `export-html/`
### R2 — New package: `@gsd/agent-modes`
### R2 — New package: `@sf/agent-modes`
A new workspace package at `packages/gsd-agent-modes/` that owns all run-mode and CLI code. It depends on `@gsd/agent-core`, `@gsd/pi-coding-agent`, and `@gsd/pi-tui`. It is the layer the top-level `sf-run` binary entry point assembles.
A new workspace package at `packages/sf-agent-modes/` that owns all run-mode and CLI code. It depends on `@sf/agent-core`, `@sf/pi-coding-agent`, and `@sf/pi-tui`. It is the layer the top-level `sf-run` binary entry point assembles.
Must contain:
- `modes/interactive/` (full TUI interactive mode and all components)
@ -80,32 +80,32 @@ Must contain:
### R3 — `pi-coding-agent` contains only upstream code and the extension system
After the migration, the vendored `pi-coding-agent` source must not contain files that:
- Import from `@gsd/agent-core` or `@gsd/agent-modes`
- Import from `@sf/agent-core` or `@sf/agent-modes`
- Contain SF business logic (compaction, session management, run modes, CLI)
The extension system (`src/core/extensions/`) remains in `pi-coding-agent` because it is legitimately pi-typed: extension authors write against pi's `AgentMessage`, `Model`, and `TUI` types. The virtual module map in `extensions/loader.ts` must be updated to include `@gsd/agent-core` and `@gsd/agent-modes` so extensions can import from them.
The extension system (`src/core/extensions/`) remains in `pi-coding-agent` because it is legitimately pi-typed: extension authors write against pi's `AgentMessage`, `Model`, and `TUI` types. The virtual module map in `extensions/loader.ts` must be updated to include `@sf/agent-core` and `@sf/agent-modes` so extensions can import from them.
### R4 — Public API surfaces are explicit
Each new package must have an `index.ts` that declares its public API. Internal files must not be imported by path from outside the package. Specifically:
- `web/bridge-service.ts` currently imports `AgentSessionEvent` from an internal path in `pi-coding-agent` — this must be fixed to use the public export from `@gsd/agent-core`
- `web/bridge-service.ts` currently imports `AgentSessionEvent` from an internal path in `pi-coding-agent` — this must be fixed to use the public export from `@sf/agent-core`
- Any other internal-path imports identified during migration must be fixed
### R5 — Build order is updated
The workspace build script must be updated to build packages in dependency order:
1. `@gsd/pi-agent-core`, `@gsd/pi-ai`, `@gsd/pi-tui` (parallel, no dependencies between them)
2. `@gsd/pi-coding-agent`
3. `@gsd/agent-core`
4. `@gsd/agent-modes`
1. `@sf/pi-agent-core`, `@sf/pi-ai`, `@sf/pi-tui` (parallel, no dependencies between them)
2. `@sf/pi-coding-agent`
3. `@sf/agent-core`
4. `@sf/agent-modes`
5. `sf-run` (top-level binary)
### R6 — No change to the extension loader's public interface
Extensions are loaded by `pi-coding-agent`'s jiti-based loader. The virtual module map (`STATIC_BUNDLED_MODULES`) must be updated to resolve `@gsd/agent-core` and `@gsd/agent-modes` alongside the existing pi package mappings. This requires both a map entry and a top-level bundle import in `loader.ts` (see ADR-009 for the exact diff). Extension authors must not need to change their import paths.
Extensions are loaded by `pi-coding-agent`'s jiti-based loader. The virtual module map (`STATIC_BUNDLED_MODULES`) must be updated to resolve `@sf/agent-core` and `@sf/agent-modes` alongside the existing pi package mappings. This requires both a map entry and a top-level bundle import in `loader.ts` (see ADR-009 for the exact diff). Extension authors must not need to change their import paths.
## Open Questions
1. Does `clearQueue()` on `AgentSession` need to be added to a public type export, or is it already accessible to the auto-mode extension that uses it?
2. Does `buildSessionContext()` on `SessionManager` need a public re-export from `@gsd/agent-core`?
3. Should `@gsd/agent-modes` re-export `createAgentSession()` as a convenience, or should consumers always import it from `@gsd/agent-core` directly?
2. Does `buildSessionContext()` on `SessionManager` need a public re-export from `@sf/agent-core`?
3. Should `@sf/agent-modes` re-export `createAgentSession()` as a convenience, or should consumers always import it from `@sf/agent-core` directly?

198
docs/dev/agent-knowledge-index.md
View file

@ -21,30 +21,30 @@ Use when:
Read first:
- `/Users/lexchristopherson/.gsd/docs/what-is-pi/01-what-pi-is.md`
- `/Users/lexchristopherson/.gsd/docs/what-is-pi/04-the-architecture-how-everything-fits-together.md`
- `/Users/lexchristopherson/.gsd/docs/what-is-pi/05-the-agent-loop-how-pi-thinks.md`
- `/Users/lexchristopherson/.sf/docs/what-is-pi/01-what-pi-is.md`
- `/Users/lexchristopherson/.sf/docs/what-is-pi/04-the-architecture-how-everything-fits-together.md`
- `/Users/lexchristopherson/.sf/docs/what-is-pi/05-the-agent-loop-how-pi-thinks.md`
Read together when relevant:
- `/Users/lexchristopherson/.gsd/docs/what-is-pi/06-tools-how-pi-acts-on-the-world.md`
- `/Users/lexchristopherson/.gsd/docs/what-is-pi/07-sessions-memory-that-branches.md`
- `/Users/lexchristopherson/.gsd/docs/what-is-pi/08-compaction-how-pi-manages-context-limits.md`
- `/Users/lexchristopherson/.gsd/docs/what-is-pi/09-the-customization-stack.md`
- `/Users/lexchristopherson/.gsd/docs/what-is-pi/10-providers-models-multi-model-by-default.md`
- `/Users/lexchristopherson/.gsd/docs/what-is-pi/13-context-files-project-instructions.md`
- `/Users/lexchristopherson/.sf/docs/what-is-pi/06-tools-how-pi-acts-on-the-world.md`
- `/Users/lexchristopherson/.sf/docs/what-is-pi/07-sessions-memory-that-branches.md`
- `/Users/lexchristopherson/.sf/docs/what-is-pi/08-compaction-how-pi-manages-context-limits.md`
- `/Users/lexchristopherson/.sf/docs/what-is-pi/09-the-customization-stack.md`
- `/Users/lexchristopherson/.sf/docs/what-is-pi/10-providers-models-multi-model-by-default.md`
- `/Users/lexchristopherson/.sf/docs/what-is-pi/13-context-files-project-instructions.md`
Follow-up if needed:
- `/Users/lexchristopherson/.gsd/docs/what-is-pi/03-the-four-modes-of-operation.md`
- `/Users/lexchristopherson/.gsd/docs/what-is-pi/11-the-interactive-tui.md`
- `/Users/lexchristopherson/.gsd/docs/what-is-pi/12-the-message-queue-talking-while-pi-thinks.md`
- `/Users/lexchristopherson/.gsd/docs/what-is-pi/14-the-sdk-rpc-embedding-pi.md`
- `/Users/lexchristopherson/.gsd/docs/what-is-pi/15-pi-packages-the-ecosystem.md`
- `/Users/lexchristopherson/.gsd/docs/what-is-pi/16-why-pi-matters-what-makes-it-different.md`
- `/Users/lexchristopherson/.gsd/docs/what-is-pi/17-file-reference-all-documentation.md`
- `/Users/lexchristopherson/.gsd/docs/what-is-pi/18-quick-reference-commands-shortcuts.md`
- `/Users/lexchristopherson/.gsd/docs/what-is-pi/19-building-branded-apps-on-top-of-pi.md`
- `/Users/lexchristopherson/.sf/docs/what-is-pi/03-the-four-modes-of-operation.md`
- `/Users/lexchristopherson/.sf/docs/what-is-pi/11-the-interactive-tui.md`
- `/Users/lexchristopherson/.sf/docs/what-is-pi/12-the-message-queue-talking-while-pi-thinks.md`
- `/Users/lexchristopherson/.sf/docs/what-is-pi/14-the-sdk-rpc-embedding-pi.md`
- `/Users/lexchristopherson/.sf/docs/what-is-pi/15-pi-packages-the-ecosystem.md`
- `/Users/lexchristopherson/.sf/docs/what-is-pi/16-why-pi-matters-what-makes-it-different.md`
- `/Users/lexchristopherson/.sf/docs/what-is-pi/17-file-reference-all-documentation.md`
- `/Users/lexchristopherson/.sf/docs/what-is-pi/18-quick-reference-commands-shortcuts.md`
- `/Users/lexchristopherson/.sf/docs/what-is-pi/19-building-branded-apps-on-top-of-pi.md`
## Context engineering, hooks, and context flow
@ -60,16 +60,16 @@ Use when:
Read first:
- `/Users/lexchristopherson/.gsd/docs/context-and-hooks/01-the-context-pipeline.md`
- `/Users/lexchristopherson/.gsd/docs/context-and-hooks/02-hook-reference.md`
- `/Users/lexchristopherson/.sf/docs/context-and-hooks/01-the-context-pipeline.md`
- `/Users/lexchristopherson/.sf/docs/context-and-hooks/02-hook-reference.md`
Read together when relevant:
- `/Users/lexchristopherson/.gsd/docs/context-and-hooks/03-context-injection-patterns.md`
- `/Users/lexchristopherson/.gsd/docs/context-and-hooks/04-message-types-and-llm-visibility.md`
- `/Users/lexchristopherson/.gsd/docs/context-and-hooks/05-inter-extension-communication.md`
- `/Users/lexchristopherson/.gsd/docs/context-and-hooks/06-advanced-patterns-from-source.md`
- `/Users/lexchristopherson/.gsd/docs/context-and-hooks/07-the-system-prompt-anatomy.md`
- `/Users/lexchristopherson/.sf/docs/context-and-hooks/03-context-injection-patterns.md`
- `/Users/lexchristopherson/.sf/docs/context-and-hooks/04-message-types-and-llm-visibility.md`
- `/Users/lexchristopherson/.sf/docs/context-and-hooks/05-inter-extension-communication.md`
- `/Users/lexchristopherson/.sf/docs/context-and-hooks/06-advanced-patterns-from-source.md`
- `/Users/lexchristopherson/.sf/docs/context-and-hooks/07-the-system-prompt-anatomy.md`
## Extension development
@ -80,37 +80,37 @@ Use when:
Read first:
- `/Users/lexchristopherson/.gsd/docs/extending-pi/01-what-are-extensions.md`
- `/Users/lexchristopherson/.gsd/docs/extending-pi/02-architecture-mental-model.md`
- `/Users/lexchristopherson/.gsd/docs/extending-pi/03-getting-started.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/01-what-are-extensions.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/02-architecture-mental-model.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/03-getting-started.md`
Read together when relevant:
- `/Users/lexchristopherson/.gsd/docs/extending-pi/06-the-extension-lifecycle.md`
- `/Users/lexchristopherson/.gsd/docs/extending-pi/07-events-the-nervous-system.md`
- `/Users/lexchristopherson/.gsd/docs/extending-pi/08-extensioncontext-what-you-can-access.md`
- `/Users/lexchristopherson/.gsd/docs/extending-pi/09-extensionapi-what-you-can-do.md`
- `/Users/lexchristopherson/.gsd/docs/extending-pi/10-custom-tools-giving-the-llm-new-abilities.md`
- `/Users/lexchristopherson/.gsd/docs/extending-pi/11-custom-commands-user-facing-actions.md`
- `/Users/lexchristopherson/.gsd/docs/extending-pi/14-custom-rendering-controlling-what-the-user-sees.md`
- `/Users/lexchristopherson/.gsd/docs/extending-pi/25-slash-command-subcommand-patterns.md` # for subcommand-style slash command UX via getArgumentCompletions()
- `/Users/lexchristopherson/.gsd/docs/extending-pi/15-system-prompt-modification.md`
- `/Users/lexchristopherson/.gsd/docs/extending-pi/22-key-rules-gotchas.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/06-the-extension-lifecycle.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/07-events-the-nervous-system.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/08-extensioncontext-what-you-can-access.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/09-extensionapi-what-you-can-do.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/10-custom-tools-giving-the-llm-new-abilities.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/11-custom-commands-user-facing-actions.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/14-custom-rendering-controlling-what-the-user-sees.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/25-slash-command-subcommand-patterns.md` # for subcommand-style slash command UX via getArgumentCompletions()
- `/Users/lexchristopherson/.sf/docs/extending-pi/15-system-prompt-modification.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/22-key-rules-gotchas.md`
Follow-up if needed:
- `/Users/lexchristopherson/.gsd/docs/extending-pi/04-extension-locations-discovery.md`
- `/Users/lexchristopherson/.gsd/docs/extending-pi/05-extension-structure-styles.md`
- `/Users/lexchristopherson/.gsd/docs/extending-pi/12-custom-ui-visual-components.md`
- `/Users/lexchristopherson/.gsd/docs/extending-pi/13-state-management-persistence.md`
- `/Users/lexchristopherson/.gsd/docs/extending-pi/16-compaction-session-control.md`
- `/Users/lexchristopherson/.gsd/docs/extending-pi/17-model-provider-management.md`
- `/Users/lexchristopherson/.gsd/docs/extending-pi/18-remote-execution-tool-overrides.md`
- `/Users/lexchristopherson/.gsd/docs/extending-pi/19-packaging-distribution.md`
- `/Users/lexchristopherson/.gsd/docs/extending-pi/20-mode-behavior.md`
- `/Users/lexchristopherson/.gsd/docs/extending-pi/21-error-handling.md`
- `/Users/lexchristopherson/.gsd/docs/extending-pi/23-file-reference-documentation.md`
- `/Users/lexchristopherson/.gsd/docs/extending-pi/24-file-reference-example-extensions.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/04-extension-locations-discovery.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/05-extension-structure-styles.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/12-custom-ui-visual-components.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/13-state-management-persistence.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/16-compaction-session-control.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/17-model-provider-management.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/18-remote-execution-tool-overrides.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/19-packaging-distribution.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/20-mode-behavior.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/21-error-handling.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/23-file-reference-documentation.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/24-file-reference-example-extensions.md`
## Pi UI and TUI
@ -121,35 +121,35 @@ Use when:
Read first:
- `/Users/lexchristopherson/.gsd/docs/pi-ui-tui/01-the-ui-architecture.md`
- `/Users/lexchristopherson/.gsd/docs/pi-ui-tui/03-entry-points-how-ui-gets-on-screen.md`
- `/Users/lexchristopherson/.gsd/docs/pi-ui-tui/22-quick-reference-all-ui-apis.md`
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/01-the-ui-architecture.md`
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/03-entry-points-how-ui-gets-on-screen.md`
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/22-quick-reference-all-ui-apis.md`
Read together when relevant:
- `/Users/lexchristopherson/.gsd/docs/pi-ui-tui/04-built-in-dialog-methods.md`
- `/Users/lexchristopherson/.gsd/docs/pi-ui-tui/05-persistent-ui-elements.md`
- `/Users/lexchristopherson/.gsd/docs/pi-ui-tui/06-ctx-ui-custom-full-custom-components.md`
- `/Users/lexchristopherson/.gsd/docs/pi-ui-tui/07-built-in-components-the-building-blocks.md`
- `/Users/lexchristopherson/.gsd/docs/pi-ui-tui/12-overlays-floating-modals-and-panels.md`
- `/Users/lexchristopherson/.gsd/docs/pi-ui-tui/13-custom-editors-replacing-the-input.md`
- `/Users/lexchristopherson/.gsd/docs/pi-ui-tui/14-tool-rendering-custom-tool-display.md`
- `/Users/lexchristopherson/.gsd/docs/pi-ui-tui/15-message-rendering-custom-message-display.md`
- `/Users/lexchristopherson/.gsd/docs/pi-ui-tui/21-common-mistakes-and-how-to-avoid-them.md`
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/04-built-in-dialog-methods.md`
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/05-persistent-ui-elements.md`
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/06-ctx-ui-custom-full-custom-components.md`
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/07-built-in-components-the-building-blocks.md`
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/12-overlays-floating-modals-and-panels.md`
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/13-custom-editors-replacing-the-input.md`
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/14-tool-rendering-custom-tool-display.md`
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/15-message-rendering-custom-message-display.md`
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/21-common-mistakes-and-how-to-avoid-them.md`
Follow-up if needed:
- `/Users/lexchristopherson/.gsd/docs/pi-ui-tui/02-the-component-interface-foundation-of-everything.md`
- `/Users/lexchristopherson/.gsd/docs/pi-ui-tui/08-high-level-components-from-pi-coding-agent.md`
- `/Users/lexchristopherson/.gsd/docs/pi-ui-tui/09-keyboard-input-how-to-handle-keys.md`
- `/Users/lexchristopherson/.gsd/docs/pi-ui-tui/10-line-width-the-cardinal-rule.md`
- `/Users/lexchristopherson/.gsd/docs/pi-ui-tui/11-theming-colors-and-styles.md`
- `/Users/lexchristopherson/.gsd/docs/pi-ui-tui/16-performance-caching-and-invalidation.md`
- `/Users/lexchristopherson/.gsd/docs/pi-ui-tui/17-theme-changes-and-invalidation.md`
- `/Users/lexchristopherson/.gsd/docs/pi-ui-tui/18-ime-support-the-focusable-interface.md`
- `/Users/lexchristopherson/.gsd/docs/pi-ui-tui/19-building-a-complete-component-step-by-step.md`
- `/Users/lexchristopherson/.gsd/docs/pi-ui-tui/20-real-world-patterns-from-examples.md`
- `/Users/lexchristopherson/.gsd/docs/pi-ui-tui/23-file-reference-example-extensions-with-ui.md`
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/02-the-component-interface-foundation-of-everything.md`
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/08-high-level-components-from-pi-coding-agent.md`
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/09-keyboard-input-how-to-handle-keys.md`
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/10-line-width-the-cardinal-rule.md`
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/11-theming-colors-and-styles.md`
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/16-performance-caching-and-invalidation.md`
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/17-theme-changes-and-invalidation.md`
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/18-ime-support-the-focusable-interface.md`
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/19-building-a-complete-component-step-by-step.md`
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/20-real-world-patterns-from-examples.md`
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/23-file-reference-example-extensions-with-ui.md`
## Building coding agents
@ -161,38 +161,38 @@ Use when:
Read first:
- `/Users/lexchristopherson/.gsd/docs/building-coding-agents/01-work-decomposition.md`
- `/Users/lexchristopherson/.gsd/docs/building-coding-agents/06-maximizing-agent-autonomy-superpowers.md`
- `/Users/lexchristopherson/.gsd/docs/building-coding-agents/11-god-tier-context-engineering.md`
- `/Users/lexchristopherson/.gsd/docs/building-coding-agents/12-handling-ambiguity-contradiction.md`
- `/Users/lexchristopherson/.gsd/docs/building-coding-agents/26-cross-cutting-themes-where-all-4-models-converge.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/01-work-decomposition.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/06-maximizing-agent-autonomy-superpowers.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/11-god-tier-context-engineering.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/12-handling-ambiguity-contradiction.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/26-cross-cutting-themes-where-all-4-models-converge.md`
Read together when relevant:
- `/Users/lexchristopherson/.gsd/docs/building-coding-agents/03-state-machine-context-management.md`
- `/Users/lexchristopherson/.gsd/docs/building-coding-agents/04-optimal-storage-for-project-context.md`
- `/Users/lexchristopherson/.gsd/docs/building-coding-agents/05-parallelization-strategy.md`
- `/Users/lexchristopherson/.gsd/docs/building-coding-agents/07-system-prompt-llm-vs-deterministic-split.md`
- `/Users/lexchristopherson/.gsd/docs/building-coding-agents/08-speed-optimization.md`
- `/Users/lexchristopherson/.gsd/docs/building-coding-agents/10-top-10-pitfalls-to-avoid.md`
- `/Users/lexchristopherson/.gsd/docs/building-coding-agents/17-irreversible-operations-safety-architecture.md`
- `/Users/lexchristopherson/.gsd/docs/building-coding-agents/20-error-taxonomy-routing.md`
- `/Users/lexchristopherson/.gsd/docs/building-coding-agents/24-security-trust-boundaries.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/03-state-machine-context-management.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/04-optimal-storage-for-project-context.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/05-parallelization-strategy.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/07-system-prompt-llm-vs-deterministic-split.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/08-speed-optimization.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/10-top-10-pitfalls-to-avoid.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/17-irreversible-operations-safety-architecture.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/20-error-taxonomy-routing.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/24-security-trust-boundaries.md`
Follow-up if needed:
- `/Users/lexchristopherson/.gsd/docs/building-coding-agents/02-what-to-keep-discard-from-human-engineering.md`
- `/Users/lexchristopherson/.gsd/docs/building-coding-agents/09-top-10-tips-for-a-world-class-agent.md`
- `/Users/lexchristopherson/.gsd/docs/building-coding-agents/13-long-running-memory-fidelity.md`
- `/Users/lexchristopherson/.gsd/docs/building-coding-agents/14-multi-agent-semantic-conflict-resolution.md`
- `/Users/lexchristopherson/.gsd/docs/building-coding-agents/15-legacy-code-brownfield-onboarding.md`
- `/Users/lexchristopherson/.gsd/docs/building-coding-agents/16-encoding-taste-aesthetics.md`
- `/Users/lexchristopherson/.gsd/docs/building-coding-agents/18-the-handoff-problem-agent-human-maintainability.md`
- `/Users/lexchristopherson/.gsd/docs/building-coding-agents/19-when-to-scrap-and-start-over.md`
- `/Users/lexchristopherson/.gsd/docs/building-coding-agents/21-cost-quality-tradeoff-model-routing.md`
- `/Users/lexchristopherson/.gsd/docs/building-coding-agents/22-cross-project-learning-reusable-intelligence.md`
- `/Users/lexchristopherson/.gsd/docs/building-coding-agents/23-evolution-across-project-scale.md`
- `/Users/lexchristopherson/.gsd/docs/building-coding-agents/25-designing-for-non-technical-users-vibe-coders.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/02-what-to-keep-discard-from-human-engineering.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/09-top-10-tips-for-a-world-class-agent.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/13-long-running-memory-fidelity.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/14-multi-agent-semantic-conflict-resolution.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/15-legacy-code-brownfield-onboarding.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/16-encoding-taste-aesthetics.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/18-the-handoff-problem-agent-human-maintainability.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/19-when-to-scrap-and-start-over.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/21-cost-quality-tradeoff-model-routing.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/22-cross-project-learning-reusable-intelligence.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/23-evolution-across-project-scale.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/25-designing-for-non-technical-users-vibe-coders.md`
## Pi product docs

18
docs/dev/architecture.md
View file

@ -5,31 +5,31 @@ SF is a TypeScript application built on the [Pi SDK](https://github.com/badlogic
## System Structure
```
gsd (CLI binary)
sf (CLI binary)
└─ loader.ts Sets PI_PACKAGE_DIR, SF env vars, dynamic-imports cli.ts
└─ cli.ts Wires SDK managers, loads extensions, starts InteractiveMode
├─ onboarding.ts First-run setup wizard (LLM provider + tool keys)
├─ wizard.ts Env hydration from stored auth.json credentials
├─ app-paths.ts ~/.gsd/agent/, ~/.gsd/sessions/, auth.json
├─ resource-loader.ts Syncs bundled extensions + agents to ~/.gsd/agent/
├─ app-paths.ts ~/.sf/agent/, ~/.sf/sessions/, auth.json
├─ resource-loader.ts Syncs bundled extensions + agents to ~/.sf/agent/
└─ src/resources/
├─ extensions/gsd/ Core SF extension
├─ extensions/sf/ Core SF extension
├─ extensions/... 23 supporting extensions
├─ agents/ scout, researcher, worker
├─ AGENTS.md Agent routing instructions
└─ SF-WORKFLOW.md Manual bootstrap protocol
gsd headless Headless mode — CI/cron orchestration via RPC child process
gsd --mode mcp MCP server mode — exposes tools over stdin/stdout
sf headless Headless mode — CI/cron orchestration via RPC child process
sf --mode mcp MCP server mode — exposes tools over stdin/stdout
vscode-extension/ VS Code extension — chat participant (@gsd), sidebar dashboard, RPC integration
vscode-extension/ VS Code extension — chat participant (@sf), sidebar dashboard, RPC integration
```
## Key Design Decisions
### State Lives on Disk
`.gsd/` is the sole source of truth. Auto mode reads it, writes it, and advances based on what it finds. No in-memory state survives across sessions. This enables crash recovery, multi-terminal steering, and session resumption.
`.sf/` is the sole source of truth. Auto mode reads it, writes it, and advances based on what it finds. No in-memory state survives across sessions. This enables crash recovery, multi-terminal steering, and session resumption.
### Two-File Loader Pattern
@ -41,7 +41,7 @@ vscode-extension/ VS Code extension — chat participant (@gsd), sidebar
### Always-Overwrite Sync
Bundled extensions and agents are synced to `~/.gsd/agent/` on every launch, not just first run. This means `npm update -g` takes effect immediately.
Bundled extensions and agents are synced to `~/.sf/agent/` on every launch, not just first run. This means `npm update -g` takes effect immediately.
### Lazy Provider Loading

4
docs/dev/ci-cd-pipeline.md
View file

@ -80,7 +80,7 @@ docker run --rm -v $(pwd):/workspace ghcr.io/singularity-forge/sf-run:latest --v
CI automatically detects when a PR contains only documentation changes (`.md` files and `docs/` content). When docs-only:
- **Skipped:** `build`, `windows-portability` (no code to compile or test)
- **Still runs:** `lint` (secret scanning, `.gsd/` check), `docs-check` (prompt injection scan)
- **Still runs:** `lint` (secret scanning, `.sf/` check), `docs-check` (prompt injection scan)
This saves CI minutes on documentation PRs while still enforcing security checks.
@ -147,7 +147,7 @@ For `@dev` or `@next` rollbacks, the next successful merge will overwrite the ta
| Secret: `ANTHROPIC_API_KEY` | Prod environment only |
| Secret: `OPENAI_API_KEY` | Prod environment only |
| Variable: `RUN_LIVE_TESTS` | `false` (set to `true` to enable live LLM tests) |
| GHCR | Enabled for the `gsd-build` org |
| GHCR | Enabled for the `sf-build` org |
### Docker Images

10
docs/dev/context-and-hooks/07-the-system-prompt-anatomy.md
View file

@ -20,7 +20,7 @@ When `buildSystemPrompt()` runs, it assembles sections in this exact order:
│ 2. Append system prompt (APPEND_SYSTEM.md) │
│ │
│ 3. Project context files │
│ ├── ~/.gsd/agent/AGENTS.md (global) │
│ ├── ~/.sf/agent/AGENTS.md (global) │
│ ├── Ancestor AGENTS.md / CLAUDE.md files │
│ └── cwd AGENTS.md / CLAUDE.md │
│ │
@ -72,7 +72,7 @@ Pi documentation (read only when the user asks about pi itself...):
### SYSTEM.md Override (full replacement)
If `.gsd/SYSTEM.md` (project) or `~/.gsd/agent/SYSTEM.md` (global) exists, its contents **completely replace** the default base prompt above. The tools list, guidelines, pi docs pointers — all gone. You own the entire base.
If `.sf/SYSTEM.md` (project) or `~/.sf/agent/SYSTEM.md` (global) exists, its contents **completely replace** the default base prompt above. The tools list, guidelines, pi docs pointers — all gone. You own the entire base.
Project takes precedence over global. Only one SYSTEM.md is used (first found wins).
@ -124,7 +124,7 @@ Guidelines are assembled dynamically based on which tools are active:
## Section 2: Append System Prompt
If `.gsd/APPEND_SYSTEM.md` (project) or `~/.gsd/agent/APPEND_SYSTEM.md` (global) exists, its contents are appended after the base prompt.
If `.sf/APPEND_SYSTEM.md` (project) or `~/.sf/agent/APPEND_SYSTEM.md` (global) exists, its contents are appended after the base prompt.
This is the safe way to add project-wide instructions without replacing the default prompt. It works with both the default base and a custom SYSTEM.md.
@ -135,7 +135,7 @@ This is the safe way to add project-wide instructions without replacing the defa
Pi walks the filesystem collecting context files:
```
1. ~/.gsd/agent/AGENTS.md (global)
1. ~/.sf/agent/AGENTS.md (global)
2. Walk from cwd upward to root:
- Each directory: check for AGENTS.md, then CLAUDE.md (first found wins per directory)
- Files are collected root-down (ancestors first, cwd last)
@ -148,7 +148,7 @@ All found files are concatenated under a "# Project Context" header:
Project-specific instructions and guidelines:
## /Users/you/.gsd/agent/AGENTS.md
## /Users/you/.sf/agent/AGENTS.md
[global AGENTS.md content]

4
docs/dev/extending-pi/03-getting-started.md
View file

@ -3,7 +3,7 @@
### Minimal Extension
Create `~/.gsd/agent/extensions/my-extension.ts`:
Create `~/.sf/agent/extensions/my-extension.ts`:
```typescript
import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
@ -27,7 +27,7 @@ pi
### Hot Reload
Extensions in auto-discovered locations (`~/.gsd/agent/extensions/` or `.gsd/extensions/`) can be hot-reloaded:
Extensions in auto-discovered locations (`~/.sf/agent/extensions/` or `.sf/extensions/`) can be hot-reloaded:
```
/reload

8
docs/dev/extending-pi/04-extension-locations-discovery.md
View file

@ -5,10 +5,10 @@
| Location | Scope |
|----------|-------|
| `~/.gsd/agent/extensions/*.ts` | Global (all projects) |
| `~/.gsd/agent/extensions/*/index.ts` | Global (subdirectory) |
| `.gsd/extensions/*.ts` | Project-local |
| `.gsd/extensions/*/index.ts` | Project-local (subdirectory) |
| `~/.sf/agent/extensions/*.ts` | Global (all projects) |
| `~/.sf/agent/extensions/*/index.ts` | Global (subdirectory) |
| `.sf/extensions/*.ts` | Project-local |
| `.sf/extensions/*/index.ts` | Project-local (subdirectory) |
### Additional Paths (via settings.json)

6
docs/dev/extending-pi/05-extension-structure-styles.md
View file

@ -4,14 +4,14 @@
### Single File (simplest)
```
~/.gsd/agent/extensions/
~/.sf/agent/extensions/
└── my-extension.ts
```
### Directory with index.ts (multi-file)
```
~/.gsd/agent/extensions/
~/.sf/agent/extensions/
└── my-extension/
├── index.ts # Entry point (must export default function)
├── tools.ts
@ -21,7 +21,7 @@
### Package with Dependencies (npm packages needed)
```
~/.gsd/agent/extensions/
~/.sf/agent/extensions/
└── my-extension/
├── package.json
├── package-lock.json

8
docs/dev/extending-pi/25-slash-command-subcommand-patterns.md
View file

@ -175,7 +175,7 @@ This is how `/wt switch`, `/wt merge`, and `/wt rm` can suggest current worktree
The worktree extension uses this exact structure in:
- `/Users/lexchristopherson/.gsd/agent/extensions/worktree/index.ts`
- `/Users/lexchristopherson/.sf/agent/extensions/worktree/index.ts`
It defines:
@ -307,9 +307,9 @@ description: "Manage foo items: /foo new|list|delete [name]"
Read these alongside this pattern:
- `/Users/lexchristopherson/.gsd/docs/extending-pi/11-custom-commands-user-facing-actions.md`
- `/Users/lexchristopherson/.gsd/docs/extending-pi/09-extensionapi-what-you-can-do.md`
- `/Users/lexchristopherson/.gsd/agent/extensions/worktree/index.ts`
- `/Users/lexchristopherson/.sf/docs/extending-pi/11-custom-commands-user-facing-actions.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/09-extensionapi-what-you-can-do.md`
- `/Users/lexchristopherson/.sf/agent/extensions/worktree/index.ts`
## Summary

4
docs/dev/pi-context-optimization-opportunities.md
View file

@ -95,7 +95,7 @@ COMPACTION_RESERVE_TOKENS = contextWindow * (1 - COMPACTION_THRESHOLD_PERCENT)
## 5. Context File Deduplication and Trim
**Current state** (`packages/pi-coding-agent/src/core/resource-loader.ts`, lines 84–109):
- Searches from `~/.gsd/agent/` → ancestor dirs → cwd
- Searches from `~/.sf/agent/` → ancestor dirs → cwd
- Deduplicates by *file path* but not by *content*
- Entire file content concatenated verbatim into system prompt — no trimming, no summarization
@ -178,7 +178,7 @@ interface CostCheckpointEvent {
}
```
SF extension could consume these events to surface per-milestone cost in `/gsd stats` and flag milestones that are disproportionately expensive — enabling budget-aware planning.
SF extension could consume these events to surface per-milestone cost in `/sf stats` and flag milestones that are disproportionately expensive — enabling budget-aware planning.
---

6
docs/dev/proposals/698-browser-tools-feature-additions.md
View file

@ -55,7 +55,7 @@ Save cookies, localStorage, sessionStorage, and auth tokens to disk. Restore the
|---|---|
| **New tools in** | `tools/session.ts` (extend existing file) |
| **Playwright API** | `context.storageState()` for cookies + localStorage; `page.evaluate()` for sessionStorage (not included in Playwright's storageState) |
| **Storage location** | Session artifacts directory: `.gsd/browser-state/<name>.json` |
| **Storage location** | Session artifacts directory: `.sf/browser-state/<name>.json` |
| **Tool signatures** | `browser_save_state({ name?: string })` → `{ path, cookieCount, localStorageOrigins }` / `browser_restore_state({ name?: string })` → `{ restored, cookieCount }` |
| **Restore mechanism** | `browser.newContext({ storageState: path })` for new sessions; `context.addCookies()` + `page.evaluate()` for mid-session restore |
| **Security** | State files may contain auth tokens — add to `.gitignore` pattern, warn in tool output |
@ -68,7 +68,7 @@ Save cookies, localStorage, sessionStorage, and auth tokens to disk. Restore the
- [ ] Saves sessionStorage via `page.evaluate()` (per-origin)
- [ ] Restores state on new browser context launch
- [ ] Restores state mid-session (cookies + evaluate injection)
- [ ] State files written to `.gsd/browser-state/` and gitignored
- [ ] State files written to `.sf/browser-state/` and gitignored
- [ ] Tool output shows count of restored items, never displays secret values
---
@ -174,7 +174,7 @@ Compare two screenshots pixel-by-pixel, return a diff image and similarity score
| **New file** | `tools/visual-diff.ts` |
| **Comparison library** | `pixelmatch` (lightweight, ~200 lines, MIT) or Playwright's built-in `expect(page).toHaveScreenshot()` comparison |
| **Tool signature** | `browser_visual_diff({ baseline?: string, current?: string, threshold?: number })` → `{ match: boolean, similarity: number, diffPixels: number, diffImagePath?: string }` |
| **Baseline management** | Save baselines to `.gsd/browser-baselines/`; auto-name by URL + viewport |
| **Baseline management** | Save baselines to `.sf/browser-baselines/`; auto-name by URL + viewport |
| **Dependencies** | `pixelmatch` + `pngjs` (new deps, ~50KB total) or use Playwright's built-in comparator |
| **Estimated effort** | **10–14 hours** |
| **Risk** | Medium — anti-aliasing and dynamic content (timestamps, ads) cause false positives; threshold tuning needed |

36
docs/dev/superpowers/plans/2026-03-17-cicd-pipeline.md
View file

@ -23,9 +23,9 @@
| `.github/workflows/cleanup-dev-versions.yml` | Weekly scheduled cleanup of old `-dev.` npm versions |
| `scripts/version-stamp.mjs` | Reads `package.json` version, appends `-dev.<sha>`, writes back |
| `tests/smoke/run.ts` | Smoke test runner — discovers and executes all smoke tests |
| `tests/smoke/test-version.ts` | Verify `gsd --version` outputs valid semver |
| `tests/smoke/test-help.ts` | Verify `gsd --help` exits 0 and contains expected output |
| `tests/smoke/test-init.ts` | Verify `gsd init` creates expected files in a temp dir |
| `tests/smoke/test-version.ts` | Verify `sf --version` outputs valid semver |
| `tests/smoke/test-help.ts` | Verify `sf --help` exits 0 and contains expected output |
| `tests/smoke/test-init.ts` | Verify `sf init` creates expected files in a temp dir |
| `tests/fixtures/provider.ts` | `FixtureProvider` — wraps `ApiProvider`, records/replays turns |
| `tests/fixtures/run.ts` | Fixture test runner — loads recordings, replays via `FixtureProvider` |
| `tests/fixtures/record.ts` | Recording helper — runs a session with `SF_FIXTURE_MODE=record` |
@ -141,13 +141,13 @@ RUN npm install -g sf-run@${SF_VERSION}
# Default working directory for user projects
WORKDIR /workspace
ENTRYPOINT ["gsd"]
ENTRYPOINT ["sf"]
CMD ["--help"]
```
- [ ] **Step 2: Verify builder stage builds**
Run: `docker build --target builder -t gsd-ci-builder-test .`
Run: `docker build --target builder -t sf-ci-builder-test .`
Expected: Completes successfully (may take 5-10 min first time)
- [ ] **Step 3: Verify runtime stage builds**
@ -225,7 +225,7 @@ if (failed > 0) process.exit(1);
```typescript
// tests/smoke/test-version.ts
// Verifies that `gsd --version` outputs valid semver-like string.
// Verifies that `sf --version` outputs valid semver-like string.
// When SF_SMOKE_BINARY is set (CI), uses that binary directly.
// Otherwise falls back to npx sf-run.
@ -248,7 +248,7 @@ console.log(`version: ${output}`);
```typescript
// tests/smoke/test-help.ts
// Verifies that `gsd --help` exits 0 and contains expected keywords.
// Verifies that `sf --help` exits 0 and contains expected keywords.
import { execFileSync } from "child_process";
@ -257,7 +257,7 @@ const output = bin
? execFileSync(bin, ["--help"], { encoding: "utf8", timeout: 30_000 })
: execFileSync("npx", ["sf-run", "--help"], { encoding: "utf8", timeout: 30_000 });
const requiredKeywords = ["gsd", "usage"];
const requiredKeywords = ["sf", "usage"];
for (const keyword of requiredKeywords) {
if (!output.toLowerCase().includes(keyword)) {
console.error(`Missing keyword "${keyword}" in help output`);
@ -272,14 +272,14 @@ console.log("help output OK");
```typescript
// tests/smoke/test-init.ts
// Verifies that `gsd init` creates expected files in a temp directory.
// Verifies that `sf init` creates expected files in a temp directory.
import { execFileSync } from "child_process";
import { mkdtempSync, existsSync, rmSync } from "fs";
import { join } from "path";
import { tmpdir } from "os";
const tmp = mkdtempSync(join(tmpdir(), "gsd-smoke-init-"));
const tmp = mkdtempSync(join(tmpdir(), "sf-smoke-init-"));
try {
const bin = process.env.SF_SMOKE_BINARY;
@ -291,9 +291,9 @@ try {
env: { ...process.env, SF_NON_INTERACTIVE: "1" },
});
// Check that .gsd directory was created
if (!existsSync(join(tmp, ".gsd"))) {
console.error("Expected .gsd/ directory not found after init");
// Check that .sf directory was created
if (!existsSync(join(tmp, ".sf"))) {
console.error("Expected .sf/ directory not found after init");
process.exit(1);
}
@ -484,7 +484,7 @@ export class FixtureReplayer {
}
```
Note: This provider implements the core recording/replay data structures and utilities. Wiring it into the `pi-ai` registry as a drop-in `ApiProvider` (via `registerApiProvider()` from `packages/pi-ai/src/api-registry.ts`) requires importing `@gsd/pi-ai` internals, which couples tests to the build output. This integration is deferred to a follow-up task after the pipeline is operational. The current implementation validates fixture format, turn sequencing, and replay correctness independently.
Note: This provider implements the core recording/replay data structures and utilities. Wiring it into the `pi-ai` registry as a drop-in `ApiProvider` (via `registerApiProvider()` from `packages/pi-ai/src/api-registry.ts`) requires importing `@sf/pi-ai` internals, which couples tests to the build output. This integration is deferred to a follow-up task after the pipeline is operational. The current implementation validates fixture format, turn sequencing, and replay correctness independently.
- [ ] **Step 2: Verify the file has no syntax errors**
@ -1038,7 +1038,7 @@ jobs:
mkdir /tmp/smoke-test && cd /tmp/smoke-test
npm init -y
npm install sf-run@dev
npx gsd --version
npx sf --version
# ─── TEST STAGE ────────────────────────────────────────────
test-verify:
@ -1067,7 +1067,7 @@ jobs:
- name: Run CLI smoke tests
run: npm run test:smoke
env:
SF_SMOKE_BINARY: gsd # Use globally installed binary, not npx
SF_SMOKE_BINARY: sf # Use globally installed binary, not npx
- name: Run fixture replay tests
run: npm run test:fixtures
@ -1141,7 +1141,7 @@ jobs:
mkdir /tmp/prod-smoke && cd /tmp/prod-smoke
npm init -y
npm install sf-run@latest
npx gsd --version
npx sf --version
# ─── CI BUILDER IMAGE (conditional) ────────────────────────
update-builder:
@ -1395,7 +1395,7 @@ These steps require repo admin access and cannot be automated:
- `RUN_LIVE_TESTS` → `false` by default on `prod` (set to `true` to enable)
4. **Enable GHCR:**
- Ensure GitHub Container Registry is enabled for the `gsd-build` org
- Ensure GitHub Container Registry is enabled for the `sf-build` org
5. **Test the pipeline end-to-end:**
- Merge a test PR to `main`

6
docs/dev/superpowers/specs/2026-03-17-cicd-pipeline-design.md
View file

@ -80,7 +80,7 @@ The `-dev.` prerelease identifier is distinct from the existing `-next.` convent
### Native Binary Strategy for Dev Publishes
Dev versions (`@dev` tag) use the native binaries from the most recent stable `build-native.yml` release. The `optionalDependencies` in `package.json` use `>=` ranges, so a `-dev.` version of `sf-run` resolves the latest stable `@gsd-build/engine-*` packages from the registry.
Dev versions (`@dev` tag) use the native binaries from the most recent stable `build-native.yml` release. The `optionalDependencies` in `package.json` use `>=` ranges, so a `-dev.` version of `sf-run` resolves the latest stable `@sf-build/engine-*` packages from the registry.
If a PR modifies Rust native crate code (`native/` directory), the dev publish will bundle stale native binaries. This is acceptable because:
- Native crate changes are infrequent and always accompanied by a `v*` tag release
@ -183,11 +183,11 @@ FixtureProvider (intercept layer)
### Integration Design
The `FixtureProvider` implements the `Provider` interface from `@gsd/pi-ai` (the same interface all 20+ built-in providers implement). It registers itself via environment variable detection at provider initialization:
The `FixtureProvider` implements the `Provider` interface from `@sf/pi-ai` (the same interface all 20+ built-in providers implement). It registers itself via environment variable detection at provider initialization:
```typescript
// Pseudocode — actual implementation will follow pi-ai patterns
import type { Provider, StreamingResponse } from "@gsd/pi-ai";
import type { Provider, StreamingResponse } from "@sf/pi-ai";
class FixtureProvider implements Provider {
// In record mode: wraps the real provider, saves responses

2
docs/dev/what-is-pi/07-sessions-memory-that-branches.md
View file

@ -7,7 +7,7 @@ Sessions are pi's memory system. They're more sophisticated than simple conversa
Sessions are **JSONL files** (one JSON object per line). Each line is an "entry" with a `type`, `id`, and `parentId`:
```
~/.gsd/agent/sessions/--path--to--project--/<timestamp>_<uuid>.jsonl
~/.sf/agent/sessions/--path--to--project--/<timestamp>_<uuid>.jsonl
```
### The Entry Tree

14
docs/dev/what-is-pi/09-the-customization-stack.md
View file

@ -26,8 +26,8 @@ Pi has four layers of customization, each serving a different purpose:
TypeScript modules with full runtime access. They can hook into every event, register tools the LLM can call, add commands, render custom UI, override built-in behavior, and register model providers. Extensions are the most powerful customization mechanism.
**Placement:**
- `~/.gsd/agent/extensions/` (global)
- `.gsd/extensions/` (project-local)
- `~/.sf/agent/extensions/` (global)
- `.sf/extensions/` (project-local)
See the companion doc **Pi-Extensions-Complete-Guide.md** for the full 50KB reference.
@ -66,7 +66,7 @@ my-skill/
Markdown files that expand into prompts via `/name`. Simple text expansion with positional argument support (`$1`, `$2`, `$@`).
```markdown
<!-- ~/.gsd/agent/prompts/review.md -->
<!-- ~/.sf/agent/prompts/review.md -->
---
description: Review staged git changes
---
@ -80,8 +80,8 @@ Focus area: $1
Usage: `/review "error handling"` → expands with `$1` = "error handling"
**Placement:**
- `~/.gsd/agent/prompts/` (global)
- `.gsd/prompts/` (project-local)
- `~/.sf/agent/prompts/` (global)
- `.sf/prompts/` (project-local)
### Themes
@ -90,7 +90,7 @@ JSON files defining the color palette for the TUI. Hot-reload: edit the file and
**Built-in:** `dark`, `light`
**Placement:**
- `~/.gsd/agent/themes/` (global)
- `.gsd/themes/` (project-local)
- `~/.sf/agent/themes/` (global)
- `.sf/themes/` (project-local)
---

4
docs/dev/what-is-pi/10-providers-models-multi-model-by-default.md
View file

@ -40,10 +40,10 @@ pi --list-models gemini # Search by name
### Custom Providers
Add providers via `~/.gsd/agent/models.json` (simple) or extensions (advanced with OAuth, custom streaming):
Add providers via `~/.sf/agent/models.json` (simple) or extensions (advanced with OAuth, custom streaming):
```json
// ~/.gsd/agent/models.json
// ~/.sf/agent/models.json
{
"providers": [{
"name": "my-proxy",

10
docs/dev/what-is-pi/13-context-files-project-instructions.md
View file

@ -5,7 +5,7 @@ Pi loads instruction files automatically at startup:
### AGENTS.md (or CLAUDE.md)
Pi looks for `AGENTS.md` or `CLAUDE.md` in:
1. `~/.gsd/agent/AGENTS.md` (global)
1. `~/.sf/agent/AGENTS.md` (global)
2. Every parent directory from cwd up to filesystem root
3. Current directory
@ -14,12 +14,12 @@ All matching files are concatenated and included in the system prompt. Use these
### System Prompt Override
Replace the default system prompt entirely:
- `.gsd/SYSTEM.md` (project)
- `~/.gsd/agent/SYSTEM.md` (global)
- `.sf/SYSTEM.md` (project)
- `~/.sf/agent/SYSTEM.md` (global)
Append to it instead:
- `.gsd/APPEND_SYSTEM.md` (project)
- `~/.gsd/agent/APPEND_SYSTEM.md` (global)
- `.sf/APPEND_SYSTEM.md` (project)
- `~/.sf/agent/APPEND_SYSTEM.md` (global)
### File Arguments

62
docs/dev/what-is-pi/19-building-branded-apps-on-top-of-pi.md
View file

@ -5,7 +5,7 @@ This document covers the part that the extension docs, SDK docs, RPC docs, and p
**How do you build your own product on top of pi** so users run **your** app, **your** command, and **your** UI rather than installing and managing pi directly?
Examples:
- a branded CLI like `gsd`
- a branded CLI like `sf`
- a desktop app that uses pi as its backend engine
- a web or Electron app that uses pi sessions, tools, and event streaming
- an internal company agent product built on pi primitives
@ -14,7 +14,7 @@ The short answer is:
- **Yes, you can build your own branded app on top of pi**
- **No, end users do not need to install pi globally** if you ship your own app that depends on pi packages
- **No, you do not have to rely on `~/.gsd`** if you embed pi with custom paths and storage
- **No, you do not have to rely on `~/.sf`** if you embed pi with custom paths and storage
- **Yes, you can bundle your own extensions, prompts, themes, skills, and providers** inside your app
The rest of this document explains the architecture choices, storage choices, packaging strategies, and practical tradeoffs.
@ -59,7 +59,7 @@ You can ship your own app that depends on:
That means a branded command like:
```bash
gsd
sf
```
can be **your** executable, backed by pi internals, without asking users to separately install and run `pi`.
@ -76,19 +76,19 @@ pi
you can ship:
```bash
npm install -g my-gsd
npm install -g my-sf
# or a standalone binary / packaged desktop app
gsd
sf
```
And inside `gsd`, you import pi packages and create your own session, UI, storage, and resource loading behavior.
And inside `sf`, you import pi packages and create your own session, UI, storage, and resource loading behavior.
---
## 19.3 The Second Biggest Misconception: `~/.gsd` Is a Default, Not a Requirement
## 19.3 The Second Biggest Misconception: `~/.sf` Is a Default, Not a Requirement
Pi CLI defaults to `~/.gsd/agent`, but embedded applications are not forced to use it.
Pi CLI defaults to `~/.sf/agent`, but embedded applications are not forced to use it.
When you use `createAgentSession()`, you can control:
@ -102,13 +102,13 @@ When you use `createAgentSession()`, you can control:
That means your app can store state under:
- `~/.gsd/agent`
- `~/.sf/agent`
- `~/Library/Application Support/SF`
- `%APPDATA%/SF`
- an app-local portable directory
- a project-local directory
instead of `~/.gsd`.
instead of `~/.sf`.
### Things you can relocate
@ -138,7 +138,7 @@ Before writing code, decide which of these architectures you actually want.
### Architecture A: Branded Node CLI or TUI using the SDK
This is the most natural fit for tools like `gsd`.
This is the most natural fit for tools like `sf`.
You create your own executable and call `createAgentSession()` directly.
@ -152,7 +152,7 @@ You create your own executable and call `createAgentSession()` directly.
- type-safe
- no subprocess management
- easy to customize storage and discovery
- easiest way to remove dependency on `~/.gsd`
- easiest way to remove dependency on `~/.sf`
- easiest way to bundle built-in resources
#### Typical stack
@ -211,7 +211,7 @@ Use this decision table.
| Goal | Best Starting Point |
|------|---------------------|
| Branded CLI like `gsd` | `@mariozechner/pi-coding-agent` SDK |
| Branded CLI like `sf` | `@mariozechner/pi-coding-agent` SDK |
| Branded TUI with coding tools | `@mariozechner/pi-coding-agent` SDK |
| Desktop app with subprocess boundary | pi RPC mode |
| Non-Node integration | pi RPC mode |
@ -234,12 +234,12 @@ Use this decision table.
---
## 19.6 The Recommended Path for a Branded CLI Like `gsd`
## 19.6 The Recommended Path for a Branded CLI Like `sf`
If you want users to run:
```bash
gsd
sf
```
and you want it to feel like your product rather than "pi but renamed," the default recommendation is:
@ -269,7 +269,7 @@ A branded app should usually own its own storage hierarchy.
Example:
```text
~/.gsd/
~/.sf/
agent/
auth.json
models.json
@ -291,7 +291,7 @@ Or on macOS:
### Why this matters
If your product uses `~/.gsd`, then:
If your product uses `~/.sf`, then:
- it shares state with the user's pi installation
- branding becomes muddy
- support/debugging becomes more confusing
@ -312,7 +312,7 @@ import {
SettingsManager,
} from "@mariozechner/pi-coding-agent";
const appRoot = path.join(os.homedir(), ".gsd");
const appRoot = path.join(os.homedir(), ".sf");
const agentDir = path.join(appRoot, "agent");
const sessionsDir = path.join(appRoot, "sessions");
@ -337,7 +337,7 @@ This is the core pattern for “my app uses pi, but not as global pi.”
## 19.8 Bundling Resources Inside Your App
This is another place where people often assume they must rely on discovery from `~/.gsd` or `.gsd/`.
This is another place where people often assume they must rely on discovery from `~/.sf` or `.sf/`.
You do not.
@ -414,8 +414,8 @@ These are different product strategies.
### Discovery-driven product
You intentionally load from:
- `~/.gsd/agent/...`
- `.gsd/...`
- `~/.sf/agent/...`
- `.sf/...`
- installed pi packages
#### Good when
@ -432,7 +432,7 @@ You intentionally ship your own resources and avoid implicit user-level discover
- you do not want random user extensions affecting behavior
### Recommendation
For a branded tool like `gsd`, default to **bundled-app product** behavior.
For a branded tool like `sf`, default to **bundled-app product** behavior.
If you later add plugin support, make it explicit.
@ -671,14 +671,14 @@ A branded app should decide whether users:
Use custom `AuthStorage` paths.
```typescript
const authStorage = AuthStorage.create("/path/to/gsd/auth.json");
const authStorage = AuthStorage.create("/path/to/sf/auth.json");
```
### App-owned model config
Use your own `models.json` location or register providers dynamically.
```typescript
const modelRegistry = new ModelRegistry(authStorage, "/path/to/gsd/models.json");
const modelRegistry = new ModelRegistry(authStorage, "/path/to/sf/models.json");
```
### Custom provider strategy
@ -688,12 +688,12 @@ That keeps the app experience aligned with your branding and infrastructure.
---
## 19.18 Building a Branded `gsd` CLI: Recommended Shape
## 19.18 Building a Branded `sf` CLI: Recommended Shape
A practical architecture looks like this:
```text
my-gsd/
my-sf/
package.json
src/
cli.ts
@ -742,7 +742,7 @@ import {
SettingsManager,
} from "@mariozechner/pi-coding-agent";
const appRoot = path.join(os.homedir(), ".gsd");
const appRoot = path.join(os.homedir(), ".sf");
const agentDir = path.join(appRoot, "agent");
const sessionsDir = path.join(appRoot, "sessions");
@ -809,14 +809,14 @@ For a white-labeled product, `InteractiveMode` is a good prototyping step, not a
## 19.21 What to Avoid in a Branded Product
### Avoid accidental dependence on ambient user state
If your app silently loads from a user's `~/.gsd`, you may get:
If your app silently loads from a user's `~/.sf`, you may get:
- surprising extensions
- strange prompts
- odd themes
- hard-to-debug behavior differences
### Avoid mixing branding and storage casually
If your app is called `gsd`, but state lives in `~/.gsd`, users will notice.
If your app is called `sf`, but state lives in `~/.sf`, users will notice.
### Avoid choosing RPC just because it sounds generic
If your app is already Node/TypeScript, SDK embedding is usually simpler and more powerful.
@ -842,7 +842,7 @@ You do not need to expose:
- Uses pi internally
- App-owned directories and resources
- Explicit plugins only
- Good for productized tools like `gsd`
- Good for productized tools like `sf`
### Posture C: “Custom agent product using pi primitives”
- Uses `pi-agent-core` or selective libraries
@ -880,7 +880,7 @@ Then read the source package docs for exact API details:
If your goal is:
> “I want users to download and run `gsd`, and have it use pi internally without requiring a separate pi install or `~/.gsd` setup.”
> “I want users to download and run `sf`, and have it use pi internally without requiring a separate pi install or `~/.sf` setup.”
Then the answer is:

36
docs/user-docs/auto-mode.md
View file

@ -1,10 +1,10 @@
# Auto Mode
Auto mode is SF's autonomous execution engine. Run `/gsd auto`, walk away, come back to built software with clean git history.
Auto mode is SF's autonomous execution engine. Run `/sf auto`, walk away, come back to built software with clean git history.
## How It Works
Auto mode is a **state machine driven by files on disk**. It reads `.gsd/STATE.md`, determines the next unit of work, creates a fresh agent session, injects a focused prompt with all relevant context pre-inlined, and lets the LLM execute. When the LLM finishes, auto mode reads disk state again and dispatches the next unit.
Auto mode is a **state machine driven by files on disk**. It reads `.sf/STATE.md`, determines the next unit of work, creates a fresh agent session, injects a focused prompt with all relevant context pre-inlined, and lets the LLM execute. When the LLM finishes, auto mode reads disk state again and dispatches the next unit.
### The Loop
@ -47,7 +47,7 @@ The amount of context inlined is controlled by your [token profile](./token-opti
SF isolates milestone work using one of three modes (configured via `git.isolation` in preferences):
- **`worktree`** (default): Each milestone runs in its own git worktree at `.gsd/worktrees/<MID>/` on a `milestone/<MID>` branch. All slice work commits sequentially — no branch switching, no merge conflicts mid-milestone. When the milestone completes, it's squash-merged to main as one clean commit.
- **`worktree`** (default): Each milestone runs in its own git worktree at `.sf/worktrees/<MID>/` on a `milestone/<MID>` branch. All slice work commits sequentially — no branch switching, no merge conflicts mid-milestone. When the milestone completes, it's squash-merged to main as one clean commit.
- **`branch`**: Work happens in the project root on a `milestone/<MID>` branch. Useful for submodule-heavy repos where worktrees don't work well.
- **`none`**: Work happens directly on your current branch. No worktree, no milestone branch. Ideal for hot-reload workflows where file isolation breaks dev tooling.
@ -59,9 +59,9 @@ When your project has independent milestones, you can run them simultaneously. E
### Crash Recovery
A lock file tracks the current unit. If the session dies, the next `/gsd auto` reads the surviving session file, synthesizes a recovery briefing from every tool call that made it to disk, and resumes with full context.
A lock file tracks the current unit. If the session dies, the next `/sf auto` reads the surviving session file, synthesizes a recovery briefing from every tool call that made it to disk, and resumes with full context.
**Headless auto-restart (v2.26):** When running `gsd headless auto`, crashes trigger automatic restart with exponential backoff (5s → 10s → 30s cap, default 3 attempts). Configure with `--max-restarts N`. SIGINT/SIGTERM bypasses restart. Combined with crash recovery, this enables true overnight "run until done" execution.
**Headless auto-restart (v2.26):** When running `sf headless auto`, crashes trigger automatic restart with exponential backoff (5s → 10s → 30s cap, default 3 attempts). Configure with `--max-restarts N`. SIGINT/SIGTERM bypasses restart. Combined with crash recovery, this enables true overnight "run until done" execution.
### Provider Error Recovery
@ -95,16 +95,16 @@ The sliding-window approach reduces false positives on legitimate retries (e.g.,
### Post-Mortem Investigation (v2.40)
`/gsd forensics` is a full-access SF debugger for post-mortem analysis of auto-mode failures. It provides:
`/sf forensics` is a full-access SF debugger for post-mortem analysis of auto-mode failures. It provides:
- **Anomaly detection** — structured identification of stuck loops, cost spikes, timeouts, missing artifacts, and crashes with severity levels
- **Unit traces** — last 10 unit executions with error details and execution times
- **Metrics analysis** — cost, token counts, and execution time breakdowns
- **Doctor integration** — includes structural health issues from `/gsd doctor`
- **Doctor integration** — includes structural health issues from `/sf doctor`
- **LLM-guided investigation** — an agent session with full tool access to investigate root causes
```
/gsd forensics [optional problem description]
/sf forensics [optional problem description]
```
See [Troubleshooting](./troubleshooting.md) for more on diagnosing issues.
@ -164,13 +164,13 @@ Auto-mode pauses before each slice, presenting the slice context for discussion.
### HTML Reports (v2.26)
After a milestone completes, SF auto-generates a self-contained HTML report in `.gsd/reports/`. Reports include project summary, progress tree, slice dependency graph (SVG DAG), cost/token metrics with bar charts, execution timeline, changelog, and knowledge base. No external dependencies — all CSS and JS are inlined.
After a milestone completes, SF auto-generates a self-contained HTML report in `.sf/reports/`. Reports include project summary, progress tree, slice dependency graph (SVG DAG), cost/token metrics with bar charts, execution timeline, changelog, and knowledge base. No external dependencies — all CSS and JS are inlined.
```yaml
auto_report: true # enabled by default
```
Generate manually anytime with `/gsd export --html`, or generate reports for all milestones at once with `/gsd export --html --all` (v2.28).
Generate manually anytime with `/sf export --html`, or generate reports for all milestones at once with `/sf export --html --all` (v2.28).
### Failure Recovery (v2.28)
@ -190,7 +190,7 @@ This linear flow is easier to debug, uses less memory (no recursive call stack),
### Real-Time Health Visibility (v2.40)
Doctor issues (from `/gsd doctor`) now surface in real time across three places:
Doctor issues (from `/sf doctor`) now surface in real time across three places:
- **Dashboard widget** — health indicator with issue count and severity
- **Workflow visualizer** — issues shown in the status panel
@ -213,7 +213,7 @@ See [Configuration](./configuration.md) for skill routing preferences.
### Start
```
/gsd auto
/sf auto
```
### Pause
@ -223,7 +223,7 @@ Press **Escape**. The conversation is preserved. You can interact with the agent
### Resume
```
/gsd auto
/sf auto
```
Auto mode reads disk state and picks up where it left off.
@ -231,7 +231,7 @@ Auto mode reads disk state and picks up where it left off.
### Stop
```
/gsd stop
/sf stop
```
Stops auto mode gracefully. Can be run from a different terminal.
@ -239,7 +239,7 @@ Stops auto mode gracefully. Can be run from a different terminal.
### Steer
```
/gsd steer
/sf steer
```
Hard-steer plan documents during execution without stopping the pipeline. Changes are picked up at the next phase boundary.
@ -247,7 +247,7 @@ Hard-steer plan documents during execution without stopping the pipeline. Change
### Capture
```
/gsd capture "add rate limiting to API endpoints"
/sf capture "add rate limiting to API endpoints"
```
Fire-and-forget thought capture. Captures are triaged automatically between tasks. See [Captures & Triage](./captures-triage.md).
@ -255,14 +255,14 @@ Fire-and-forget thought capture. Captures are triaged automatically between task
### Visualize
```
/gsd visualize
/sf visualize
```
Open the workflow visualizer — interactive tabs for progress, dependencies, metrics, and timeline. See [Workflow Visualizer](./visualizer.md).
## Dashboard
`Ctrl+Alt+G` or `/gsd status` shows real-time progress:
`Ctrl+Alt+G` or `/sf status` shows real-time progress:
- Current milestone, slice, and task
- Auto mode elapsed time and phase

16
docs/user-docs/captures-triage.md
View file

@ -9,11 +9,11 @@ Captures let you fire-and-forget thoughts during auto-mode execution. Instead of
While auto-mode is running (or any time):
```
/gsd capture "add rate limiting to the API endpoints"
/gsd capture "the auth flow should support OAuth, not just JWT"
/sf capture "add rate limiting to the API endpoints"
/sf capture "the auth flow should support OAuth, not just JWT"
```
Captures are appended to `.gsd/CAPTURES.md` and triaged automatically between tasks.
Captures are appended to `.sf/CAPTURES.md` and triaged automatically between tasks.
## How It Works
@ -23,7 +23,7 @@ Captures are appended to `.gsd/CAPTURES.md` and triaged automatically between ta
capture → triage → confirm → resolve → resume
```
1. **Capture** — `/gsd capture "thought"` appends to `.gsd/CAPTURES.md` with a timestamp and unique ID
1. **Capture** — `/sf capture "thought"` appends to `.sf/CAPTURES.md` with a timestamp and unique ID
2. **Triage** — at natural seams between tasks (in `handleAgentEnd`), SF detects pending captures and classifies them
3. **Confirm** — the user is shown the proposed resolution and confirms or adjusts
4. **Resolve** — the resolution is applied (task injection, replan trigger, deferral, etc.)
@ -55,7 +55,7 @@ The LLM classifies each capture and proposes a resolution. Plan-modifying resolu
Trigger triage manually at any time:
```
/gsd triage
/sf triage
```
This is useful when you've accumulated several captures and want to process them before the next natural seam.
@ -72,11 +72,11 @@ Capture context is automatically injected into:
## Worktree Awareness
Captures always resolve to the **original project root's** `.gsd/CAPTURES.md`, not the worktree's local copy. This ensures captures from a steering terminal are visible to the auto-mode session running in a worktree.
Captures always resolve to the **original project root's** `.sf/CAPTURES.md`, not the worktree's local copy. This ensures captures from a steering terminal are visible to the auto-mode session running in a worktree.
## Commands
| Command | Description |
|---------|-------------|
| `/gsd capture "text"` | Capture a thought (quotes optional for single words) |
| `/gsd triage` | Manually trigger triage of pending captures |
| `/sf capture "text"` | Capture a thought (quotes optional for single words) |
| `/sf triage` | Manually trigger triage of pending captures |

240
docs/user-docs/commands.md
View file

@ -4,78 +4,78 @@
| Command | Description |
|---------|-------------|
| `/gsd` | Step mode — execute one unit at a time, pause between each |
| `/gsd next` | Explicit step mode (same as `/gsd`) |
| `/gsd auto` | Autonomous mode — research, plan, execute, commit, repeat |
| `/gsd quick` | Execute a quick task with SF guarantees (atomic commits, state tracking) without full planning overhead |
| `/gsd stop` | Stop auto mode gracefully |
| `/gsd pause` | Pause auto-mode (preserves state, `/gsd auto` to resume) |
| `/gsd steer` | Hard-steer plan documents during execution |
| `/gsd discuss` | Discuss architecture and decisions (works alongside auto mode) |
| `/gsd status` | Progress dashboard |
| `/gsd widget` | Cycle dashboard widget: full / small / min / off |
| `/gsd queue` | Queue and reorder future milestones (safe during auto mode) |
| `/gsd capture` | Fire-and-forget thought capture (works during auto mode) |
| `/gsd triage` | Manually trigger triage of pending captures |
| `/gsd dispatch` | Dispatch a specific phase directly (research, plan, execute, complete, reassess, uat, replan) |
| `/gsd history` | View execution history (supports `--cost`, `--phase`, `--model` filters) |
| `/gsd forensics` | Full-access SF debugger — structured anomaly detection, unit traces, and LLM-guided root-cause analysis for auto-mode failures |
| `/gsd cleanup` | Clean up SF state files and stale worktrees |
| `/gsd visualize` | Open workflow visualizer (progress, deps, metrics, timeline) |
| `/gsd export --html` | Generate self-contained HTML report for current or completed milestone |
| `/gsd export --html --all` | Generate retrospective reports for all milestones at once |
| `/gsd update` | Update SF to the latest version in-session |
| `/gsd knowledge` | Add persistent project knowledge (rule, pattern, or lesson) |
| `/gsd fast` | Toggle service tier for supported models (prioritized API routing) |
| `/gsd rate` | Rate last unit's model tier (over/ok/under) — improves adaptive routing |
| `/gsd changelog` | Show categorized release notes |
| `/gsd logs` | Browse activity logs, debug logs, and metrics |
| `/gsd remote` | Control remote auto-mode |
| `/gsd help` | Categorized command reference with descriptions for all SF subcommands |
| `/sf` | Step mode — execute one unit at a time, pause between each |
| `/sf next` | Explicit step mode (same as `/sf`) |
| `/sf auto` | Autonomous mode — research, plan, execute, commit, repeat |
| `/sf quick` | Execute a quick task with SF guarantees (atomic commits, state tracking) without full planning overhead |
| `/sf stop` | Stop auto mode gracefully |
| `/sf pause` | Pause auto-mode (preserves state, `/sf auto` to resume) |
| `/sf steer` | Hard-steer plan documents during execution |
| `/sf discuss` | Discuss architecture and decisions (works alongside auto mode) |
| `/sf status` | Progress dashboard |
| `/sf widget` | Cycle dashboard widget: full / small / min / off |
| `/sf queue` | Queue and reorder future milestones (safe during auto mode) |
| `/sf capture` | Fire-and-forget thought capture (works during auto mode) |
| `/sf triage` | Manually trigger triage of pending captures |
| `/sf dispatch` | Dispatch a specific phase directly (research, plan, execute, complete, reassess, uat, replan) |
| `/sf history` | View execution history (supports `--cost`, `--phase`, `--model` filters) |
| `/sf forensics` | Full-access SF debugger — structured anomaly detection, unit traces, and LLM-guided root-cause analysis for auto-mode failures |
| `/sf cleanup` | Clean up SF state files and stale worktrees |
| `/sf visualize` | Open workflow visualizer (progress, deps, metrics, timeline) |
| `/sf export --html` | Generate self-contained HTML report for current or completed milestone |
| `/sf export --html --all` | Generate retrospective reports for all milestones at once |
| `/sf update` | Update SF to the latest version in-session |
| `/sf knowledge` | Add persistent project knowledge (rule, pattern, or lesson) |
| `/sf fast` | Toggle service tier for supported models (prioritized API routing) |
| `/sf rate` | Rate last unit's model tier (over/ok/under) — improves adaptive routing |
| `/sf changelog` | Show categorized release notes |
| `/sf logs` | Browse activity logs, debug logs, and metrics |
| `/sf remote` | Control remote auto-mode |
| `/sf help` | Categorized command reference with descriptions for all SF subcommands |
## Configuration & Diagnostics
| Command | Description |
|---------|-------------|
| `/gsd prefs` | Model selection, timeouts, budget ceiling |
| `/gsd mode` | Switch workflow mode (solo/team) with coordinated defaults for milestone IDs, git commit behavior, and documentation |
| `/gsd config` | Re-run the provider setup wizard (LLM provider + tool keys) |
| `/gsd keys` | API key manager — list, add, remove, test, rotate, doctor |
| `/gsd doctor` | Runtime health checks with auto-fix — issues surface in real time across widget, visualizer, and HTML reports (v2.40) |
| `/gsd inspect` | Show SQLite DB diagnostics |
| `/gsd init` | Project init wizard — detect, configure, bootstrap `.gsd/` |
| `/gsd setup` | Global setup status and configuration |
| `/gsd skill-health` | Skill lifecycle dashboard — usage stats, success rates, token trends, staleness warnings |
| `/gsd skill-health <name>` | Detailed view for a single skill |
| `/gsd skill-health --declining` | Show only skills flagged for declining performance |
| `/gsd skill-health --stale N` | Show skills unused for N+ days |
| `/gsd hooks` | Show configured post-unit and pre-dispatch hooks |
| `/gsd run-hook` | Manually trigger a specific hook |
| `/gsd migrate` | Migrate a v1 `.planning` directory to `.gsd` format |
| `/sf prefs` | Model selection, timeouts, budget ceiling |
| `/sf mode` | Switch workflow mode (solo/team) with coordinated defaults for milestone IDs, git commit behavior, and documentation |
| `/sf config` | Re-run the provider setup wizard (LLM provider + tool keys) |
| `/sf keys` | API key manager — list, add, remove, test, rotate, doctor |
| `/sf doctor` | Runtime health checks with auto-fix — issues surface in real time across widget, visualizer, and HTML reports (v2.40) |
| `/sf inspect` | Show SQLite DB diagnostics |
| `/sf init` | Project init wizard — detect, configure, bootstrap `.sf/` |
| `/sf setup` | Global setup status and configuration |
| `/sf skill-health` | Skill lifecycle dashboard — usage stats, success rates, token trends, staleness warnings |
| `/sf skill-health <name>` | Detailed view for a single skill |
| `/sf skill-health --declining` | Show only skills flagged for declining performance |
| `/sf skill-health --stale N` | Show skills unused for N+ days |
| `/sf hooks` | Show configured post-unit and pre-dispatch hooks |
| `/sf run-hook` | Manually trigger a specific hook |
| `/sf migrate` | Migrate a v1 `.planning` directory to `.sf` format |
## Milestone Management
| Command | Description |
|---------|-------------|
| `/gsd new-milestone` | Create a new milestone |
| `/gsd skip` | Prevent a unit from auto-mode dispatch |
| `/gsd undo` | Revert last completed unit |
| `/gsd undo-task` | Reset a specific task's completion state (DB + markdown) |
| `/gsd reset-slice` | Reset a slice and all its tasks (DB + markdown) |
| `/gsd park` | Park a milestone — skip without deleting |
| `/gsd unpark` | Reactivate a parked milestone |
| Discard milestone | Available via `/gsd` wizard → "Milestone actions" → "Discard" |
| `/sf new-milestone` | Create a new milestone |
| `/sf skip` | Prevent a unit from auto-mode dispatch |
| `/sf undo` | Revert last completed unit |
| `/sf undo-task` | Reset a specific task's completion state (DB + markdown) |
| `/sf reset-slice` | Reset a slice and all its tasks (DB + markdown) |
| `/sf park` | Park a milestone — skip without deleting |
| `/sf unpark` | Reactivate a parked milestone |
| Discard milestone | Available via `/sf` wizard → "Milestone actions" → "Discard" |
## Parallel Orchestration
| Command | Description |
|---------|-------------|
| `/gsd parallel start` | Analyze eligibility, confirm, and start workers |
| `/gsd parallel status` | Show all workers with state, progress, and cost |
| `/gsd parallel stop [MID]` | Stop all workers or a specific milestone's worker |
| `/gsd parallel pause [MID]` | Pause all workers or a specific one |
| `/gsd parallel resume [MID]` | Resume paused workers |
| `/gsd parallel merge [MID]` | Merge completed milestones back to main |
| `/sf parallel start` | Analyze eligibility, confirm, and start workers |
| `/sf parallel status` | Show all workers with state, progress, and cost |
| `/sf parallel stop [MID]` | Stop all workers or a specific milestone's worker |
| `/sf parallel pause [MID]` | Pause all workers or a specific one |
| `/sf parallel resume [MID]` | Resume paused workers |
| `/sf parallel merge [MID]` | Merge completed milestones back to main |
See [Parallel Orchestration](./parallel-orchestration.md) for full documentation.
@ -83,50 +83,50 @@ See [Parallel Orchestration](./parallel-orchestration.md) for full documentation
| Command | Description |
|---------|-------------|
| `/gsd start` | Start a workflow template (bugfix, spike, feature, hotfix, refactor, security-audit, dep-upgrade, full-project) |
| `/gsd start resume` | Resume an in-progress workflow |
| `/gsd templates` | List available workflow templates |
| `/gsd templates info <name>` | Show detailed template info |
| `/sf start` | Start a workflow template (bugfix, spike, feature, hotfix, refactor, security-audit, dep-upgrade, full-project) |
| `/sf start resume` | Resume an in-progress workflow |
| `/sf templates` | List available workflow templates |
| `/sf templates info <name>` | Show detailed template info |
## Custom Workflows (v2.42)
| Command | Description |
|---------|-------------|
| `/gsd workflow new` | Create a new workflow definition (via skill) |
| `/gsd workflow run <name>` | Create a run and start auto-mode |
| `/gsd workflow list` | List workflow runs |
| `/gsd workflow validate <name>` | Validate a workflow definition YAML |
| `/gsd workflow pause` | Pause custom workflow auto-mode |
| `/gsd workflow resume` | Resume paused custom workflow auto-mode |
| `/sf workflow new` | Create a new workflow definition (via skill) |
| `/sf workflow run <name>` | Create a run and start auto-mode |
| `/sf workflow list` | List workflow runs |
| `/sf workflow validate <name>` | Validate a workflow definition YAML |
| `/sf workflow pause` | Pause custom workflow auto-mode |
| `/sf workflow resume` | Resume paused custom workflow auto-mode |
## Extensions
| Command | Description |
|---------|-------------|
| `/gsd extensions list` | List all extensions and their status |
| `/gsd extensions enable <id>` | Enable a disabled extension |
| `/gsd extensions disable <id>` | Disable an extension |
| `/gsd extensions info <id>` | Show extension details |
| `/sf extensions list` | List all extensions and their status |
| `/sf extensions enable <id>` | Enable a disabled extension |
| `/sf extensions disable <id>` | Disable an extension |
| `/sf extensions info <id>` | Show extension details |
## cmux Integration
| Command | Description |
|---------|-------------|
| `/gsd cmux status` | Show cmux detection, prefs, and capabilities |
| `/gsd cmux on` | Enable cmux integration |
| `/gsd cmux off` | Disable cmux integration |
| `/gsd cmux notifications on/off` | Toggle cmux desktop notifications |
| `/gsd cmux sidebar on/off` | Toggle cmux sidebar metadata |
| `/gsd cmux splits on/off` | Toggle cmux visual subagent splits |
| `/sf cmux status` | Show cmux detection, prefs, and capabilities |
| `/sf cmux on` | Enable cmux integration |
| `/sf cmux off` | Disable cmux integration |
| `/sf cmux notifications on/off` | Toggle cmux desktop notifications |
| `/sf cmux sidebar on/off` | Toggle cmux sidebar metadata |
| `/sf cmux splits on/off` | Toggle cmux visual subagent splits |
## GitHub Sync (v2.39)
| Command | Description |
|---------|-------------|
| `/github-sync bootstrap` | Initial setup — creates GitHub Milestones, Issues, and draft PRs from current `.gsd/` state |
| `/github-sync bootstrap` | Initial setup — creates GitHub Milestones, Issues, and draft PRs from current `.sf/` state |
| `/github-sync status` | Show sync mapping counts (milestones, slices, tasks) |
Enable with `github.enabled: true` in preferences. Requires `gh` CLI installed and authenticated. Sync mapping is persisted in `.gsd/.github-sync.json`.
Enable with `github.enabled: true` in preferences. Requires `gh` CLI installed and authenticated. Sync mapping is persisted in `.sf/.github-sync.json`.
## Git Commands
@ -164,54 +164,54 @@ Enable with `github.enabled: true` in preferences. Requires `gh` CLI installed a
| Flag | Description |
|------|-------------|
| `gsd` | Start a new interactive session |
| `gsd --continue` (`-c`) | Resume the most recent session for the current directory |
| `gsd --model <id>` | Override the default model for this session |
| `gsd --print "msg"` (`-p`) | Single-shot prompt mode (no TUI) |
| `gsd --mode <text\|json\|rpc\|mcp>` | Output mode for non-interactive use |
| `gsd --list-models [search]` | List available models and exit |
| `gsd --web [path]` | Start browser-based web interface (optional project path) |
| `gsd --worktree` (`-w`) [name] | Start session in a git worktree (auto-generates name if omitted) |
| `gsd --no-session` | Disable session persistence |
| `gsd --extension <path>` | Load an additional extension (can be repeated) |
| `gsd --append-system-prompt <text>` | Append text to the system prompt |
| `gsd --tools <list>` | Comma-separated list of tools to enable |
| `gsd --version` (`-v`) | Print version and exit |
| `gsd --help` (`-h`) | Print help and exit |
| `gsd sessions` | Interactive session picker — list all saved sessions for the current directory and choose one to resume |
| `gsd --debug` | Enable structured JSONL diagnostic logging for troubleshooting dispatch and state issues |
| `gsd config` | Set up global API keys for search and docs tools (saved to `~/.gsd/agent/auth.json`, applies to all projects). See [Global API Keys](./configuration.md#global-api-keys-gsd-config). |
| `gsd update` | Update SF to the latest version |
| `gsd headless new-milestone` | Create a new milestone from a context file (headless — no TUI required) |
| `sf` | Start a new interactive session |
| `sf --continue` (`-c`) | Resume the most recent session for the current directory |
| `sf --model <id>` | Override the default model for this session |
| `sf --print "msg"` (`-p`) | Single-shot prompt mode (no TUI) |
| `sf --mode <text\|json\|rpc\|mcp>` | Output mode for non-interactive use |
| `sf --list-models [search]` | List available models and exit |
| `sf --web [path]` | Start browser-based web interface (optional project path) |
| `sf --worktree` (`-w`) [name] | Start session in a git worktree (auto-generates name if omitted) |
| `sf --no-session` | Disable session persistence |
| `sf --extension <path>` | Load an additional extension (can be repeated) |
| `sf --append-system-prompt <text>` | Append text to the system prompt |
| `sf --tools <list>` | Comma-separated list of tools to enable |
| `sf --version` (`-v`) | Print version and exit |
| `sf --help` (`-h`) | Print help and exit |
| `sf sessions` | Interactive session picker — list all saved sessions for the current directory and choose one to resume |
| `sf --debug` | Enable structured JSONL diagnostic logging for troubleshooting dispatch and state issues |
| `sf config` | Set up global API keys for search and docs tools (saved to `~/.sf/agent/auth.json`, applies to all projects). See [Global API Keys](./configuration.md#global-api-keys-sf-config). |
| `sf update` | Update SF to the latest version |
| `sf headless new-milestone` | Create a new milestone from a context file (headless — no TUI required) |
## Headless Mode
`gsd headless` runs `/gsd` commands without a TUI — designed for CI, cron jobs, and scripted automation. It spawns a child process in RPC mode, auto-responds to interactive prompts, detects completion, and exits with meaningful exit codes.
`sf headless` runs `/sf` commands without a TUI — designed for CI, cron jobs, and scripted automation. It spawns a child process in RPC mode, auto-responds to interactive prompts, detects completion, and exits with meaningful exit codes.
```bash
# Run auto mode (default)
gsd headless
sf headless
# Run a single unit
gsd headless next
sf headless next
# Instant JSON snapshot — no LLM, ~50ms
gsd headless query
sf headless query
# With timeout for CI
gsd headless --timeout 600000 auto
sf headless --timeout 600000 auto
# Force a specific phase
gsd headless dispatch plan
sf headless dispatch plan
# Create a new milestone from a context file and start auto mode
gsd headless new-milestone --context brief.md --auto
sf headless new-milestone --context brief.md --auto
# Create a milestone from inline text
gsd headless new-milestone --context-text "Build a REST API with auth"
sf headless new-milestone --context-text "Build a REST API with auth"
# Pipe context from stdin
echo "Build a CLI tool" | gsd headless new-milestone --context -
echo "Build a CLI tool" | sf headless new-milestone --context -
```
| Flag | Description |
@ -226,20 +226,20 @@ echo "Build a CLI tool" | gsd headless new-milestone --context -
**Exit codes:** `0` = complete, `1` = error or timeout, `2` = blocked.
Any `/gsd` subcommand works as a positional argument — `gsd headless status`, `gsd headless doctor`, `gsd headless dispatch execute`, etc.
Any `/sf` subcommand works as a positional argument — `sf headless status`, `sf headless doctor`, `sf headless dispatch execute`, etc.
### `gsd headless query`
### `sf headless query`
Returns a single JSON object with the full project snapshot — no LLM session, no RPC child, instant response (~50ms). This is the recommended way for orchestrators and scripts to inspect SF state.
```bash
gsd headless query | jq '.state.phase'
sf headless query | jq '.state.phase'
# "executing"
gsd headless query | jq '.next'
sf headless query | jq '.next'
# {"action":"dispatch","unitType":"execute-task","unitId":"M001/S01/T03"}
gsd headless query | jq '.cost.total'
sf headless query | jq '.cost.total'
# 4.25
```
@ -270,21 +270,21 @@ gsd headless query | jq '.cost.total'
## MCP Server Mode
`gsd --mode mcp` runs SF as a [Model Context Protocol](https://modelcontextprotocol.io) server over stdin/stdout. This exposes all SF tools (read, write, edit, bash, etc.) to external AI clients — Claude Desktop, VS Code Copilot, and any MCP-compatible host.
`sf --mode mcp` runs SF as a [Model Context Protocol](https://modelcontextprotocol.io) server over stdin/stdout. This exposes all SF tools (read, write, edit, bash, etc.) to external AI clients — Claude Desktop, VS Code Copilot, and any MCP-compatible host.
```bash
# Start SF as an MCP server
gsd --mode mcp
sf --mode mcp
```
The server registers all tools from the agent session and maps MCP `tools/list` and `tools/call` requests to SF tool definitions. It runs until the transport closes.
## In-Session Update
`/gsd update` checks npm for a newer version of SF and installs it without leaving the session.
`/sf update` checks npm for a newer version of SF and installs it without leaving the session.
```bash
/gsd update
/sf update
# Current version: v2.36.0
# Checking npm registry...
# Updated to v2.37.0. Restart SF to use the new version.
@ -294,14 +294,14 @@ If already up to date, it reports so and takes no action.
## Export
`/gsd export` generates reports of milestone work.
`/sf export` generates reports of milestone work.
```bash
# Generate HTML report for the active milestone
/gsd export --html
/sf export --html
# Generate retrospective reports for ALL milestones at once
/gsd export --html --all
/sf export --html --all
```
Reports are saved to `.gsd/reports/` with a browseable `index.html` that links to all generated snapshots.
Reports are saved to `.sf/reports/` with a browseable `index.html` that links to all generated snapshots.

82
docs/user-docs/configuration.md
View file

@ -1,20 +1,20 @@
# Configuration
SF preferences live in `~/.gsd/PREFERENCES.md` (global) or `.gsd/PREFERENCES.md` (project-local). Manage interactively with `/gsd prefs`.
SF preferences live in `~/.sf/PREFERENCES.md` (global) or `.sf/PREFERENCES.md` (project-local). Manage interactively with `/sf prefs`.
## `/gsd prefs` Commands
## `/sf prefs` Commands
| Command | Description |
|---------|-------------|
| `/gsd prefs` | Open the global preferences wizard (default) |
| `/gsd prefs global` | Interactive wizard for global preferences (`~/.gsd/PREFERENCES.md`) |
| `/gsd prefs project` | Interactive wizard for project preferences (`.gsd/PREFERENCES.md`) |
| `/gsd prefs status` | Show current preference files, merged values, and skill resolution status |
| `/gsd prefs wizard` | Alias for `/gsd prefs global` |
| `/gsd prefs setup` | Alias for `/gsd prefs wizard` — creates preferences file if missing |
| `/gsd prefs import-claude` | Import Claude marketplace plugins and skills as namespaced SF components |
| `/gsd prefs import-claude global` | Import to global scope |
| `/gsd prefs import-claude project` | Import to project scope |
| `/sf prefs` | Open the global preferences wizard (default) |
| `/sf prefs global` | Interactive wizard for global preferences (`~/.sf/PREFERENCES.md`) |
| `/sf prefs project` | Interactive wizard for project preferences (`.sf/PREFERENCES.md`) |
| `/sf prefs status` | Show current preference files, merged values, and skill resolution status |
| `/sf prefs wizard` | Alias for `/sf prefs global` |
| `/sf prefs setup` | Alias for `/sf prefs wizard` — creates preferences file if missing |
| `/sf prefs import-claude` | Import Claude marketplace plugins and skills as namespaced SF components |
| `/sf prefs import-claude global` | Import to global scope |
| `/sf prefs import-claude project` | Import to project scope |
## Preferences File Format
@ -42,20 +42,20 @@ token_profile: balanced
| Scope | Path | Applies to |
|-------|------|-----------|
| Global | `~/.gsd/PREFERENCES.md` | All projects |
| Project | `.gsd/PREFERENCES.md` | Current project only |
| Global | `~/.sf/PREFERENCES.md` | All projects |
| Project | `.sf/PREFERENCES.md` | Current project only |
**Merge behavior:**
- **Scalar fields** (`skill_discovery`, `budget_ceiling`): project wins if defined
- **Array fields** (`always_use_skills`, etc.): concatenated (global first, then project)
- **Object fields** (`models`, `git`, `auto_supervisor`): shallow-merged, project overrides per-key
## Global API Keys (`/gsd config`)
## Global API Keys (`/sf config`)
Tool API keys are stored globally in `~/.gsd/agent/auth.json` and apply to all projects automatically. Set them once with `/gsd config` — no need to configure per-project `.env` files.
Tool API keys are stored globally in `~/.sf/agent/auth.json` and apply to all projects automatically. Set them once with `/sf config` — no need to configure per-project `.env` files.
```bash
/gsd config
/sf config
```
This opens an interactive wizard showing which keys are configured and which are missing. Select a tool to enter its key.
@ -70,7 +70,7 @@ This opens an interactive wizard showing which keys are configured and which are
### How it works
1. `/gsd config` saves keys to `~/.gsd/agent/auth.json`
1. `/sf config` saves keys to `~/.sf/agent/auth.json`
2. On every session start, `loadToolApiKeys()` reads the file and sets environment variables
3. Keys apply to all projects — no per-project setup required
4. Environment variables (`export BRAVE_API_KEY=...`) take precedence over saved keys
@ -85,12 +85,12 @@ SF can connect to external MCP servers configured in project files. This is usef
SF reads MCP client configuration from these project-local paths:
- `.mcp.json`
- `.gsd/mcp.json`
- `.sf/mcp.json`
If both files exist, server names are merged and the first definition found wins. Use:
- `.mcp.json` for repo-shared MCP configuration you may want to commit
- `.gsd/mcp.json` for local-only MCP configuration you do **not** want to share
- `.sf/mcp.json` for local-only MCP configuration you do **not** want to share
### Supported transports
@ -148,15 +148,15 @@ Recommended verification order:
- Use absolute paths for local executables and scripts when possible.
- For `stdio` servers, prefer setting required environment variables directly in the MCP config instead of relying on an interactive shell profile.
- SF and `gsd-mcp-server` both hydrate supported model and tool keys saved in `~/.gsd/agent/auth.json`, so MCP configs can safely reference them through `${ENV_VAR}` placeholders without committing raw credentials.
- SF and `sf-mcp-server` both hydrate supported model and tool keys saved in `~/.sf/agent/auth.json`, so MCP configs can safely reference them through `${ENV_VAR}` placeholders without committing raw credentials.
- If a server is team-shared and safe to commit, `.mcp.json` is usually the better home.
- If a server depends on machine-local paths, personal services, or local-only secrets, prefer `.gsd/mcp.json`.
- If a server depends on machine-local paths, personal services, or local-only secrets, prefer `.sf/mcp.json`.
## Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `SF_HOME` | `~/.gsd` | Global SF directory. All paths derive from this unless individually overridden. Affects preferences, skills, sessions, and per-project state. (v2.39) |
| `SF_HOME` | `~/.sf` | Global SF directory. All paths derive from this unless individually overridden. Affects preferences, skills, sessions, and per-project state. (v2.39) |
| `SF_PROJECT_ID` | (auto-hash) | Override the automatic project identity hash. Per-project state goes to `$SF_HOME/projects/<SF_PROJECT_ID>/` instead of the computed hash. Useful for CI/CD or sharing state across clones of the same repo. (v2.39) |
| `SF_STATE_DIR` | `$SF_HOME` | Per-project state root. Controls where `projects/<repo-hash>/` directories are created. Takes precedence over `SF_HOME` for project state. |
| `SF_CODING_AGENT_DIR` | `$SF_HOME/agent` | Agent directory containing managed resources, extensions, and auth. Takes precedence over `SF_HOME` for agent paths. |
@ -191,12 +191,12 @@ models:
### Custom Model Definitions (`models.json`)
Define custom models and providers in `~/.gsd/agent/models.json`. This lets you add models not included in the default registry — useful for self-hosted endpoints (Ollama, vLLM, LM Studio), fine-tuned models, proxies, or new provider releases.
Define custom models and providers in `~/.sf/agent/models.json`. This lets you add models not included in the default registry — useful for self-hosted endpoints (Ollama, vLLM, LM Studio), fine-tuned models, proxies, or new provider releases.
SF resolves models.json with fallback logic:
1. `~/.gsd/agent/models.json` — primary (SF)
1. `~/.sf/agent/models.json` — primary (SF)
2. `~/.pi/agent/models.json` — fallback (Pi)
3. If neither exists, creates `~/.gsd/agent/models.json`
3. If neither exists, creates `~/.sf/agent/models.json`
**Quick example for local models (Ollama):**
@ -240,7 +240,7 @@ For providers not built into SF, community extensions can add full provider supp
| Extension | Provider | Models | Install |
|-----------|----------|--------|---------|
| [`pi-dashscope`](https://www.npmjs.com/package/pi-dashscope) | Alibaba DashScope (ModelStudio) | Qwen3, GLM-5, MiniMax M2.5, Kimi K2.5 | `gsd install npm:pi-dashscope` |
| [`pi-dashscope`](https://www.npmjs.com/package/pi-dashscope) | Alibaba DashScope (ModelStudio) | Qwen3, GLM-5, MiniMax M2.5, Kimi K2.5 | `sf install npm:pi-dashscope` |
Community extensions are recommended over the built-in `alibaba-coding-plan` provider for DashScope models — they use the correct OpenAI-compatible endpoint and include per-model compatibility flags for thinking mode.
@ -368,7 +368,7 @@ Public URLs (`https://example.com`, `http://8.8.8.8`) are not affected.
**Allowing specific internal hosts:**
If you need the agent to fetch from internal URLs (self-hosted docs, internal APIs behind a VPN), add their hostnames to `fetchAllowedUrls` in global settings (`~/.gsd/agent/settings.json`):
If you need the agent to fetch from internal URLs (self-hosted docs, internal APIs behind a VPN), add their hostnames to `fetchAllowedUrls` in global settings (`~/.sf/agent/settings.json`):
```json
{
@ -394,7 +394,7 @@ Auto-generate HTML reports after milestone completion:
auto_report: true # default: true
```
Reports are written to `.gsd/reports/` as self-contained HTML files with embedded CSS/JS.
Reports are written to `.sf/reports/` as self-contained HTML files with embedded CSS/JS.
### `unique_milestone_ids`
@ -420,9 +420,9 @@ git:
main_branch: main # primary branch name
merge_strategy: squash # how worktree branches merge: "squash" or "merge"
isolation: worktree # git isolation: "worktree", "branch", or "none"
commit_docs: true # commit .gsd/ artifacts to git (set false to keep local)
commit_docs: true # commit .sf/ artifacts to git (set false to keep local)
manage_gitignore: true # set false to prevent SF from modifying .gitignore
worktree_post_create: .gsd/hooks/post-worktree-create # script to run after worktree creation
worktree_post_create: .sf/hooks/post-worktree-create # script to run after worktree creation
auto_pr: false # create a PR on milestone completion (requires push_branches)
pr_target_branch: develop # target branch for auto-created PRs (default: main branch)
```
@ -438,7 +438,7 @@ git:
| `main_branch` | string | `"main"` | Primary branch name |
| `merge_strategy` | string | `"squash"` | How worktree branches merge: `"squash"` (combine all commits) or `"merge"` (preserve individual commits) |
| `isolation` | string | `"worktree"` | Auto-mode isolation: `"worktree"` (separate directory), `"branch"` (work in project root — useful for submodule-heavy repos), or `"none"` (no isolation — commits on current branch, no worktree or milestone branch) |
| `commit_docs` | boolean | `true` | Commit `.gsd/` planning artifacts to git. Set `false` to keep local-only |
| `commit_docs` | boolean | `true` | Commit `.sf/` planning artifacts to git. Set `false` to keep local-only |
| `manage_gitignore` | boolean | `true` | When `false`, SF will not modify `.gitignore` at all — no baseline patterns, no self-healing. Use if you manage your own `.gitignore` |
| `worktree_post_create` | string | (none) | Script to run after worktree creation. Receives `SOURCE_DIR` and `WORKTREE_DIR` env vars |
| `auto_pr` | boolean | `false` | Automatically create a pull request when a milestone completes. Requires `auto_push: true` and `gh` CLI installed and authenticated |
@ -450,14 +450,14 @@ Script to run after a worktree is created (both auto-mode and manual `/worktree`
```yaml
git:
worktree_post_create: .gsd/hooks/post-worktree-create
worktree_post_create: .sf/hooks/post-worktree-create
```
The script receives two environment variables:
- `SOURCE_DIR` — the original project root
- `WORKTREE_DIR` — the newly created worktree path
Example hook script (`.gsd/hooks/post-worktree-create`):
Example hook script (`.sf/hooks/post-worktree-create`):
```bash
#!/bin/bash
@ -500,7 +500,7 @@ GitHub sync configuration. When enabled, SF auto-syncs milestones, slices, and t
github:
enabled: true
repo: "owner/repo" # auto-detected from git remote if omitted
labels: [gsd, auto-generated] # labels applied to created issues/PRs
labels: [sf, auto-generated] # labels applied to created issues/PRs
project: "Project ID" # optional GitHub Project board
```
@ -513,7 +513,7 @@ github:
**Requirements:**
- `gh` CLI installed and authenticated (`gh auth login`)
- Sync mapping is persisted in `.gsd/.github-sync.json`
- Sync mapping is persisted in `.sf/.github-sync.json`
- Rate-limit aware — skips sync when GitHub API rate limit is low
**Commands:**
@ -652,13 +652,13 @@ custom_instructions:
- "Prefer functional patterns over classes"
```
For project-specific knowledge (patterns, gotchas, lessons learned), use `.gsd/KNOWLEDGE.md` instead — it's injected into every agent prompt automatically. Add entries with `/gsd knowledge rule|pattern|lesson <description>`.
For project-specific knowledge (patterns, gotchas, lessons learned), use `.sf/KNOWLEDGE.md` instead — it's injected into every agent prompt automatically. Add entries with `/sf knowledge rule|pattern|lesson <description>`.
### `RUNTIME.md` — Runtime Context (v2.39)
Declare project-level runtime context in `.gsd/RUNTIME.md`. This file is inlined into task execution prompts, giving the agent accurate information about your runtime environment without relying on hallucinated paths or URLs.
Declare project-level runtime context in `.sf/RUNTIME.md`. This file is inlined into task execution prompts, giving the agent accurate information about your runtime environment without relying on hallucinated paths or URLs.
**Location:** `.gsd/RUNTIME.md`
**Location:** `.sf/RUNTIME.md`
**Example:**
@ -711,7 +711,7 @@ context_management:
### `service_tier` (v2.42)
OpenAI service tier preference for supported models. Toggle with `/gsd fast`.
OpenAI service tier preference for supported models. Toggle with `/sf fast`.
| Value | Behavior |
|-------|----------|
@ -725,7 +725,7 @@ service_tier: priority
### `forensics_dedup` (v2.43)
Opt-in: search existing issues and PRs before filing from `/gsd forensics`. Uses additional AI tokens.
Opt-in: search existing issues and PRs before filing from `/sf forensics`. Uses additional AI tokens.
```yaml
forensics_dedup: true # default: false
@ -826,7 +826,7 @@ notifications:
auto_visualize: true
# Service tier
service_tier: priority # "priority" or "flex" (for /gsd fast)
service_tier: priority # "priority" or "flex" (for /sf fast)
# Diagnostics
forensics_dedup: true # deduplicate before filing forensics issues

8
docs/user-docs/cost-management.md
View file

@ -12,11 +12,11 @@ Every unit's metrics are captured automatically:
- **Tool calls** — number of tool invocations
- **Message counts** — assistant and user messages
Data is stored in `.gsd/metrics.json` and survives across sessions.
Data is stored in `.sf/metrics.json` and survives across sessions.
### Viewing Costs
**Dashboard:** `Ctrl+Alt+G` or `/gsd status` shows real-time cost breakdown.
**Dashboard:** `Ctrl+Alt+G` or `/sf status` shows real-time cost breakdown.
**Aggregations available:**
- By phase (research, planning, execution, completion, reassessment)
@ -85,9 +85,9 @@ See [Token Optimization](./token-optimization.md) for details.
## Tips
- Start with `balanced` profile and a generous `budget_ceiling` to establish baseline costs
- Check `/gsd status` after a few slices to see per-slice cost averages
- Check `/sf status` after a few slices to see per-slice cost averages
- Switch to `budget` profile for well-understood, repetitive work
- Use `quality` only when architectural decisions are being made
- Per-phase model selection lets you use Opus only for planning while keeping execution on Sonnet
- Enable `dynamic_routing` for automatic model downgrading on simple tasks — see [Dynamic Model Routing](./dynamic-model-routing.md)
- Use `/gsd visualize` → Metrics tab to see where your budget is going
- Use `/sf visualize` → Metrics tab to see where your budget is going

6
docs/user-docs/custom-models.md
View file

@ -1,6 +1,6 @@
# Custom Models
Add custom providers and models (Ollama, vLLM, LM Studio, proxies) via `~/.gsd/agent/models.json`.
Add custom providers and models (Ollama, vLLM, LM Studio, proxies) via `~/.sf/agent/models.json`.
## Table of Contents
@ -143,7 +143,7 @@ Shell operators (`;`, `|`, `&`, `` ` ``, `$`, `>`, `<`) are also blocked in comm
**Customizing the allowlist:**
If you use a credential tool not on the default list, override it in global settings (`~/.gsd/agent/settings.json`):
If you use a credential tool not on the default list, override it in global settings (`~/.sf/agent/settings.json`):
```json
{
@ -159,7 +159,7 @@ Alternatively, set the `SF_ALLOWED_COMMAND_PREFIXES` environment variable (comma
export SF_ALLOWED_COMMAND_PREFIXES="pass,op,sops,doppler"
```
> **Note:** This setting is global-only. Project-level settings.json (`<project>/.gsd/settings.json`) cannot override the command allowlist — this prevents a cloned repo from escalating command execution privileges.
> **Note:** This setting is global-only. Project-level settings.json (`<project>/.sf/settings.json`) cannot override the command allowlist — this prevents a cloned repo from escalating command execution privileges.
### Custom Headers

2
docs/user-docs/dynamic-model-routing.md
View file

@ -258,7 +258,7 @@ For `execute-task` units, the classifier analyzes the task plan:
### Adaptive Learning
The routing history (`.gsd/routing-history.json`) tracks success/failure per tier per unit type. If a tier's failure rate exceeds 20% for a given pattern, future classifications are bumped up. User feedback (`over`/`under`/`ok`) is weighted 2× vs automatic outcomes.
The routing history (`.sf/routing-history.json`) tracks success/failure per tier per unit type. If a tier's failure rate exceeds 20% for a given pattern, future classifications are bumped up. User feedback (`over`/`under`/`ok`) is weighted 2× vs automatic outcomes.
## Interaction with Token Profiles

80
docs/user-docs/getting-started.md
View file

@ -54,7 +54,7 @@ npm install -g sf-run
export ANTHROPIC_API_KEY="sk-ant-..."
# Option B: Use the built-in config wizard
gsd config
sf config
```
To persist the key, add the export line to `~/.zshrc`:
@ -70,24 +70,24 @@ See [Provider Setup Guide](./providers.md) for all 20+ supported providers.
```bash
cd ~/my-project # navigate to any project
gsd # start a session
sf # start a session
```
**Step 7 — Verify everything works:**
```bash
gsd --version # prints the installed version
sf --version # prints the installed version
```
Inside the session, type `/model` to confirm your LLM is connected.
> **Apple Silicon PATH fix:** If `gsd` isn't found after install, npm's global bin may not be in your PATH:
> **Apple Silicon PATH fix:** If `sf` isn't found after install, npm's global bin may not be in your PATH:
> ```bash
> echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
> source ~/.zshrc
> ```
> **oh-my-zsh conflict:** The oh-my-zsh git plugin defines `alias gsd='git svn dcommit'`. Fix with `unalias gsd 2>/dev/null` in `~/.zshrc`, or use `gsd-cli` instead.
> **oh-my-zsh conflict:** The oh-my-zsh git plugin defines `alias sf='git svn dcommit'`. Fix with `unalias sf 2>/dev/null` in `~/.zshrc`, or use `sf-cli` instead.
---
@ -126,7 +126,7 @@ npm install -g sf-run
$env:ANTHROPIC_API_KEY = "sk-ant-..."
# Option B: Use the built-in config wizard
gsd config
sf config
```
To persist the key permanently, add it via System Settings > Environment Variables, or run:
@ -141,13 +141,13 @@ See [Provider Setup Guide](./providers.md) for all 20+ supported providers.
```powershell
cd C:\Users\you\my-project # navigate to any project
gsd # start a session
sf # start a session
```
**Step 7 — Verify everything works:**
```powershell
gsd --version # prints the installed version
sf --version # prints the installed version
```
Inside the session, type `/model` to confirm your LLM is connected.
@ -160,7 +160,7 @@ Inside the session, type `/model` to confirm your LLM is connected.
> **Windows tips:**
> - Use **Windows Terminal** or **PowerShell** for the best experience. Command Prompt works but has limited color support.
> - If `gsd` isn't recognized, restart your terminal. Windows needs a fresh terminal to pick up new PATH entries.
> - If `sf` isn't recognized, restart your terminal. Windows needs a fresh terminal to pick up new PATH entries.
> - **WSL2** also works — install WSL, then follow the Linux instructions inside your distro.
---
@ -230,7 +230,7 @@ npm install -g sf-run
export ANTHROPIC_API_KEY="sk-ant-..."
# Option B: Use the built-in config wizard
gsd config
sf config
```
To persist the key, add the export line to `~/.bashrc` (or `~/.zshrc`):
@ -246,13 +246,13 @@ See [Provider Setup Guide](./providers.md) for all 20+ supported providers.
```bash
cd ~/my-project # navigate to any project
gsd # start a session
sf # start a session
```
**Step 6 — Verify everything works:**
```bash
gsd --version # prints the installed version
sf --version # prints the installed version
```
Inside the session, type `/model` to confirm your LLM is connected.
@ -280,21 +280,21 @@ Run SF in an isolated sandbox without installing Node.js on your host.
```bash
git clone https://github.com/singularity-forge/sf-run.git
cd gsd-2/docker
cd sf-2/docker
```
**Step 3 — Create and enter a sandbox:**
```bash
docker sandbox create --template . --name gsd-sandbox
docker sandbox exec -it gsd-sandbox bash
docker sandbox create --template . --name sf-sandbox
docker sandbox exec -it sf-sandbox bash
```
**Step 4 — Set your API key and run SF:**
```bash
export ANTHROPIC_API_KEY="sk-ant-..."
gsd auto "implement the feature described in issue #42"
sf auto "implement the feature described in issue #42"
```
See [Docker Sandbox docs](../../docker/README.md) for full configuration, resource limits, and compose files.
@ -317,23 +317,23 @@ Or configure per-phase models in preferences — see [Configuration](./configura
## Two Ways to Work
### Step Mode — `/gsd`
### Step Mode — `/sf`
Type `/gsd` inside a session. SF executes one unit of work at a time, pausing between each with a wizard showing what completed and what's next.
Type `/sf` inside a session. SF executes one unit of work at a time, pausing between each with a wizard showing what completed and what's next.
- **No `.gsd/` directory** — starts a discussion flow to capture your project vision
- **No `.sf/` directory** — starts a discussion flow to capture your project vision
- **Milestone exists, no roadmap** — discuss or research the milestone
- **Roadmap exists, slices pending** — plan the next slice or execute a task
- **Mid-task** — resume where you left off
Step mode keeps you in the loop, reviewing output between each step.
### Auto Mode — `/gsd auto`
### Auto Mode — `/sf auto`
Type `/gsd auto` and walk away. SF autonomously researches, plans, executes, verifies, commits, and advances through every slice until the milestone is complete.
Type `/sf auto` and walk away. SF autonomously researches, plans, executes, verifies, commits, and advances through every slice until the milestone is complete.
```
/gsd auto
/sf auto
```
See [Auto Mode](./auto-mode.md) for full details.
@ -347,20 +347,20 @@ Run auto mode in one terminal, steer from another.
**Terminal 1 — let it build:**
```bash
gsd
/gsd auto
sf
/sf auto
```
**Terminal 2 — steer while it works:**
```bash
gsd
/gsd discuss # talk through architecture decisions
/gsd status # check progress
/gsd queue # queue the next milestone
sf
/sf discuss # talk through architecture decisions
/sf status # check progress
/sf queue # queue the next milestone
```
Both terminals read and write the same `.gsd/` files. Decisions in terminal 2 are picked up at the next phase boundary automatically.
Both terminals read and write the same `.sf/` files. Decisions in terminal 2 are picked up at the next phase boundary automatically.
---
@ -374,10 +374,10 @@ Milestone → a shippable version (4-10 slices)
The iron rule: **a task must fit in one context window.** If it can't, it's two tasks.
All state lives on disk in `.gsd/`:
All state lives on disk in `.sf/`:
```
.gsd/
.sf/
PROJECT.md — what the project is right now
REQUIREMENTS.md — requirement contract
DECISIONS.md — append-only architectural decisions
@ -398,7 +398,7 @@ All state lives on disk in `.gsd/`:
SF is also available as a VS Code extension. Install from the marketplace (publisher: FluxLabs) or search for "SF" in VS Code extensions:
- **`@gsd` chat participant** — talk to the agent in VS Code Chat
- **`@sf` chat participant** — talk to the agent in VS Code Chat
- **Sidebar dashboard** — connection status, model info, token usage
- **Full command palette** — start/stop agent, switch models, export sessions
@ -411,7 +411,7 @@ The CLI (`sf-run`) must be installed first — the extension connects to it via
SF has a browser-based interface for visual project management:
```bash
gsd --web
sf --web
```
See [Web Interface](./web-interface.md) for details.
@ -421,7 +421,7 @@ See [Web Interface](./web-interface.md) for details.
## Resume a Session
```bash
gsd --continue # or gsd -c
sf --continue # or sf -c
```
Resumes the most recent session for the current directory.
@ -429,7 +429,7 @@ Resumes the most recent session for the current directory.
Browse all saved sessions:
```bash
gsd sessions
sf sessions
```
---
@ -445,7 +445,7 @@ npm update -g sf-run
Or from within a session:
```
/gsd update
/sf update
```
---
@ -454,11 +454,11 @@ Or from within a session:
| Problem | Fix |
|---------|-----|
| `command not found: gsd` | Add npm global bin to PATH (see OS-specific notes above) |
| `gsd` runs `git svn dcommit` | oh-my-zsh conflict — `unalias gsd` or use `gsd-cli` |
| `command not found: sf` | Add npm global bin to PATH (see OS-specific notes above) |
| `sf` runs `git svn dcommit` | oh-my-zsh conflict — `unalias sf` or use `sf-cli` |
| Permission errors on `npm install -g` | Fix npm prefix (see Linux notes) or use nvm |
| Can't connect to LLM | Check API key with `gsd config`, verify network access |
| `gsd` hangs on start | Check Node.js version: `node --version` (need 22+) |
| Can't connect to LLM | Check API key with `sf config`, verify network access |
| `sf` hangs on start | Check Node.js version: `node --version` (need 22+) |
For more, see [Troubleshooting](./troubleshooting.md).

14
docs/user-docs/git-strategy.md
View file

@ -8,13 +8,13 @@ SF supports three isolation modes, configured via the `git.isolation` preference
| Mode | Working Directory | Branch | Best For |
|------|-------------------|--------|----------|
| `worktree` (default) | `.gsd/worktrees/<MID>/` | `milestone/<MID>` | Most projects — full file isolation between milestones |
| `worktree` (default) | `.sf/worktrees/<MID>/` | `milestone/<MID>` | Most projects — full file isolation between milestones |
| `branch` | Project root | `milestone/<MID>` | Submodule-heavy repos where worktrees don't work well |
| `none` | Project root | Current branch (no milestone branch) | Hot-reload workflows where file isolation breaks dev tooling |
### `worktree` Mode (Default)
Each milestone gets its own git worktree at `.gsd/worktrees/<MID>/` on a `milestone/<MID>` branch. All execution happens inside the worktree. On completion, the worktree is squash-merged to main as one clean commit. The worktree and branch are then cleaned up.
Each milestone gets its own git worktree at `.sf/worktrees/<MID>/` on a `milestone/<MID>` branch. All execution happens inside the worktree. On completion, the worktree is squash-merged to main as one clean commit. The worktree and branch are then cleaned up.
This provides full file isolation — changes in a milestone can't interfere with your main working copy.
@ -95,8 +95,8 @@ These features apply only in **worktree mode**.
Auto mode creates and manages worktrees automatically:
1. When a milestone starts, a worktree is created at `.gsd/worktrees/<MID>/` on branch `milestone/<MID>`
2. Planning artifacts from `.gsd/milestones/` are copied into the worktree
1. When a milestone starts, a worktree is created at `.sf/worktrees/<MID>/` on branch `milestone/<MID>`
2. Planning artifacts from `.sf/milestones/` are copied into the worktree
3. All execution happens inside the worktree
4. On milestone completion, the worktree is squash-merged to the integration branch
5. The worktree and branch are removed
@ -148,7 +148,7 @@ git:
pre_merge_check: false # pre-merge validation
commit_type: feat # override commit type prefix
main_branch: main # primary branch name
commit_docs: true # commit .gsd/ to git
commit_docs: true # commit .sf/ to git
isolation: worktree # "worktree", "branch", or "none"
auto_pr: false # create PR on milestone completion
pr_target_branch: develop # PR target branch (default: main)
@ -170,7 +170,7 @@ This pushes the milestone branch and creates a PR targeting `develop` (or whiche
### `commit_docs: false`
When set to `false`, SF adds `.gsd/` to `.gitignore` and keeps all planning artifacts local-only. Useful for teams where only some members use SF, or when company policy requires a clean repository.
When set to `false`, SF adds `.sf/` to `.gitignore` and keeps all planning artifacts local-only. Useful for teams where only some members use SF, or when company policy requires a clean repository.
## Self-Healing
@ -180,7 +180,7 @@ SF includes automatic recovery for common git issues:
- **Stale lock files** — removes `index.lock` files from crashed processes
- **Orphaned worktrees** — detects and offers to clean up abandoned worktrees (worktree mode only)
Run `/gsd doctor` to check git health manually.
Run `/sf doctor` to check git health manually.
## Native Git Operations

10
docs/user-docs/migration.md
View file

@ -1,15 +1,15 @@
# Migration from v1
If you have projects with `.planning` directories from the original Singularity Forge (v1), you can migrate them to SF's `.gsd` format.
If you have projects with `.planning` directories from the original Singularity Forge (v1), you can migrate them to SF's `.sf` format.
## Running the Migration
```bash
# From within the project directory
/gsd migrate
/sf migrate
# Or specify a path
/gsd migrate ~/projects/my-old-project
/sf migrate ~/projects/my-old-project
```
## What Gets Migrated
@ -42,7 +42,7 @@ Migration works best with a `ROADMAP.md` file for milestone structure. Without o
After migrating, verify the output with:
```
/gsd doctor
/sf doctor
```
This checks `.gsd/` integrity and flags any structural issues.
This checks `.sf/` integrity and flags any structural issues.

2
docs/user-docs/node-lts-macos.md
View file

@ -71,5 +71,5 @@ After pinning:
```bash
node --version # v24.x.x
npm install -g sf-run
gsd --version
sf --version
```

82
docs/user-docs/parallel-orchestration.md
View file

@ -19,7 +19,7 @@ parallel:
2. Start parallel execution:
```
/gsd parallel start
/sf parallel start
```
SF scans your milestones, checks dependencies and file overlap, shows an eligibility report, and spawns workers for eligible milestones.
@ -27,13 +27,13 @@ SF scans your milestones, checks dependencies and file overlap, shows an eligibi
3. Monitor progress:
```
/gsd parallel status
/sf parallel status
```
4. Stop when done:
```
/gsd parallel stop
/sf parallel stop
```
## How It Works
@ -58,7 +58,7 @@ SF scans your milestones, checks dependencies and file overlap, shows an eligibi
│ └──────────┘ └──────────┘ └──────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ .gsd/worktrees/ .gsd/worktrees/ .gsd/worktrees/ │
│ .sf/worktrees/ .sf/worktrees/ .sf/worktrees/ │
│ M001/ M003/ M005/ │
│ (milestone/ (milestone/ (milestone/ │
│ M001 branch) M003 branch) M005 branch) │
@ -67,7 +67,7 @@ SF scans your milestones, checks dependencies and file overlap, shows an eligibi
### Worker Isolation
Each worker is a separate `gsd` process with complete isolation:
Each worker is a separate `sf` process with complete isolation:
| Resource | Isolation Method |
|----------|-----------------|
@ -75,15 +75,15 @@ Each worker is a separate `gsd` process with complete isolation:
| **Git branch** | `milestone/<MID>` — one branch per milestone |
| **State derivation** | `SF_MILESTONE_LOCK` env var — `deriveState()` only sees the assigned milestone |
| **Context window** | Separate process — each worker has its own agent sessions |
| **Metrics** | Each worktree has its own `.gsd/metrics.json` |
| **Crash recovery** | Each worktree has its own `.gsd/auto.lock` |
| **Metrics** | Each worktree has its own `.sf/metrics.json` |
| **Crash recovery** | Each worktree has its own `.sf/auto.lock` |
### Coordination
Workers and the coordinator communicate through file-based IPC:
- **Session status files** (`.gsd/parallel/<MID>.status.json`) — workers write heartbeats, the coordinator reads them
- **Signal files** (`.gsd/parallel/<MID>.signal.json`) — coordinator writes signals, workers consume them
- **Session status files** (`.sf/parallel/<MID>.status.json`) — workers write heartbeats, the coordinator reads them
- **Signal files** (`.sf/parallel/<MID>.signal.json`) — coordinator writes signals, workers consume them
- **Atomic writes** — write-to-temp + rename prevents partial reads
## Eligibility Analysis
@ -126,7 +126,7 @@ File overlaps are warnings, not blockers. Both milestones work in separate workt
## Configuration
Add to `~/.gsd/PREFERENCES.md` or `.gsd/PREFERENCES.md`:
Add to `~/.sf/PREFERENCES.md` or `.sf/PREFERENCES.md`:
```yaml
---
@ -143,26 +143,26 @@ parallel:
| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `enabled` | boolean | `false` | Master toggle. Must be `true` for `/gsd parallel` commands to work. |
| `enabled` | boolean | `false` | Master toggle. Must be `true` for `/sf parallel` commands to work. |
| `max_workers` | number (1-4) | `2` | Maximum concurrent worker processes. Higher values use more memory and API budget. |
| `budget_ceiling` | number | none | Aggregate cost ceiling in USD across all workers. When reached, no new units are dispatched. |
| `merge_strategy` | `"per-slice"` or `"per-milestone"` | `"per-milestone"` | When worktree changes merge back to main. Per-milestone waits for the full milestone to complete. |
| `auto_merge` | `"auto"`, `"confirm"`, `"manual"` | `"confirm"` | How merge-back is handled. `confirm` prompts before merging. `manual` requires explicit `/gsd parallel merge`. |
| `auto_merge` | `"auto"`, `"confirm"`, `"manual"` | `"confirm"` | How merge-back is handled. `confirm` prompts before merging. `manual` requires explicit `/sf parallel merge`. |
## Commands
| Command | Description |
|---------|-------------|
| `/gsd parallel start` | Analyze eligibility, confirm, and start workers |
| `/gsd parallel status` | Show all workers with state, units completed, and cost |
| `/gsd parallel stop` | Stop all workers (sends SIGTERM) |
| `/gsd parallel stop M002` | Stop a specific milestone's worker |
| `/gsd parallel pause` | Pause all workers (finish current unit, then wait) |
| `/gsd parallel pause M002` | Pause a specific worker |
| `/gsd parallel resume` | Resume all paused workers |
| `/gsd parallel resume M002` | Resume a specific worker |
| `/gsd parallel merge` | Merge all completed milestones back to main |
| `/gsd parallel merge M002` | Merge a specific milestone back to main |
| `/sf parallel start` | Analyze eligibility, confirm, and start workers |
| `/sf parallel status` | Show all workers with state, units completed, and cost |
| `/sf parallel stop` | Stop all workers (sends SIGTERM) |
| `/sf parallel stop M002` | Stop a specific milestone's worker |
| `/sf parallel pause` | Pause all workers (finish current unit, then wait) |
| `/sf parallel pause M002` | Pause a specific worker |
| `/sf parallel resume` | Resume all paused workers |
| `/sf parallel resume M002` | Resume a specific worker |
| `/sf parallel merge` | Merge all completed milestones back to main |
| `/sf parallel merge M002` | Merge a specific milestone back to main |
## Signal Lifecycle
@ -200,13 +200,13 @@ When milestones complete, their worktree changes need to merge back to main.
### Conflict Handling
1. `.gsd/` state files (STATE.md, metrics.json, etc.) — **auto-resolved** by accepting the milestone branch version
2. Code conflicts — **stop and report**. The merge halts, showing which files conflict. Resolve manually and retry with `/gsd parallel merge <MID>`.
1. `.sf/` state files (STATE.md, metrics.json, etc.) — **auto-resolved** by accepting the milestone branch version
2. Code conflicts — **stop and report**. The merge halts, showing which files conflict. Resolve manually and retry with `/sf parallel merge <MID>`.
### Example
```
/gsd parallel merge
/sf parallel merge
# Merge Results
@ -214,7 +214,7 @@ When milestones complete, their worktree changes need to merge back to main.
- **M003** — CONFLICT (2 file(s)):
- `src/types.ts`
- `src/middleware.ts`
Resolve conflicts manually and run `/gsd parallel merge M003` to retry.
Resolve conflicts manually and run `/sf parallel merge M003` to retry.
```
## Budget Management
@ -229,11 +229,11 @@ When `budget_ceiling` is set, the coordinator tracks aggregate cost across all w
### Doctor Integration
`/gsd doctor` detects parallel session issues:
`/sf doctor` detects parallel session issues:
- **Stale parallel sessions** — Worker process died without cleanup. Doctor finds `.gsd/parallel/*.status.json` files with dead PIDs or expired heartbeats and removes them.
- **Stale parallel sessions** — Worker process died without cleanup. Doctor finds `.sf/parallel/*.status.json` files with dead PIDs or expired heartbeats and removes them.
Run `/gsd doctor --fix` to clean up automatically.
Run `/sf doctor --fix` to clean up automatically.
### Stale Detection
@ -255,12 +255,12 @@ The coordinator runs stale detection during `refreshWorkerStatuses()` and automa
| **Budget ceiling** | Aggregate cost enforcement across all workers |
| **Signal-based shutdown** | Graceful stop via file signals + SIGTERM |
| **Doctor integration** | Detects and cleans up orphaned sessions |
| **Conflict-aware merge** | Stops on code conflicts, auto-resolves `.gsd/` state conflicts |
| **Conflict-aware merge** | Stops on code conflicts, auto-resolves `.sf/` state conflicts |
## File Layout
```
.gsd/
.sf/
├── parallel/ # Coordinator ↔ worker IPC
│ ├── M002.status.json # Worker heartbeat + progress
│ ├── M002.signal.json # Coordinator → worker signals
@ -268,7 +268,7 @@ The coordinator runs stale detection during `refreshWorkerStatuses()` and automa
│ └── M003.signal.json
├── worktrees/ # Git worktrees (one per milestone)
│ ├── M002/ # M002's isolated checkout
│ │ ├── .gsd/ # M002's own state files
│ │ ├── .sf/ # M002's own state files
│ │ │ ├── auto.lock
│ │ │ ├── metrics.json
│ │ │ └── milestones/
@ -278,7 +278,7 @@ The coordinator runs stale detection during `refreshWorkerStatuses()` and automa
└── ...
```
Both `.gsd/parallel/` and `.gsd/worktrees/` are gitignored — they're runtime-only coordination files that never get committed.
Both `.sf/parallel/` and `.sf/worktrees/` are gitignored — they're runtime-only coordination files that never get committed.
## Troubleshooting
@ -288,22 +288,22 @@ Set `parallel.enabled: true` in your preferences file.
### "No milestones are eligible for parallel execution"
All milestones are either complete or blocked by dependencies. Check `/gsd queue` to see milestone status and dependency chains.
All milestones are either complete or blocked by dependencies. Check `/sf queue` to see milestone status and dependency chains.
### Worker crashed — how to recover
Workers now persist their state to disk automatically. If a worker process dies, the coordinator detects the dead PID via heartbeat expiry and marks the worker as crashed. On restart, the worker picks up from disk state — crash recovery, worktree re-entry, and completed-unit tracking carry over from the crashed session.
1. Run `/gsd doctor --fix` to clean up stale sessions
2. Run `/gsd parallel status` to see current state
3. Re-run `/gsd parallel start` to spawn new workers for remaining milestones
1. Run `/sf doctor --fix` to clean up stale sessions
2. Run `/sf parallel status` to see current state
3. Re-run `/sf parallel start` to spawn new workers for remaining milestones
### Merge conflicts after parallel completion
1. Run `/gsd parallel merge` to see which milestones have conflicts
2. Resolve conflicts in the worktree at `.gsd/worktrees/<MID>/`
3. Retry with `/gsd parallel merge <MID>`
1. Run `/sf parallel merge` to see which milestones have conflicts
2. Resolve conflicts in the worktree at `.sf/worktrees/<MID>/`
3. Retry with `/sf parallel merge <MID>`
### Workers seem stuck
Check if budget ceiling was reached: `/gsd parallel status` shows per-worker costs. Increase `parallel.budget_ceiling` or remove it to continue.
Check if budget ceiling was reached: `/sf parallel status` shows per-worker costs. Increase `parallel.budget_ceiling` or remove it to continue.

52
docs/user-docs/providers.md
View file

@ -1,6 +1,6 @@
# Provider Setup Guide
Step-by-step setup instructions for every LLM provider SF supports. If you ran the onboarding wizard (`gsd config`) and picked a provider, you may already be configured — check with `/model` inside a session.
Step-by-step setup instructions for every LLM provider SF supports. If you ran the onboarding wizard (`sf config`) and picked a provider, you may already be configured — check with `/model` inside a session.
## Table of Contents
@ -61,7 +61,7 @@ Built-in providers have models pre-registered in SF. You only need to supply cre
export ANTHROPIC_API_KEY="sk-ant-..."
```
Or run `gsd config` and paste your key when prompted.
Or run `sf config` and paste your key when prompted.
**Get a key:** [console.anthropic.com/settings/keys](https://console.anthropic.com/settings/keys)
@ -73,7 +73,7 @@ If you have a Claude Pro or Max subscription, you can authenticate through Anthr
# Install Claude Code CLI (see https://docs.anthropic.com/en/docs/claude-code)
claude
# Sign in when prompted, then start SF
gsd
sf
```
SF detects your local Claude Code installation and uses it as the authenticated Anthropic surface. This is the TOS-compliant path for subscription users — SF never handles your subscription credentials directly.
@ -91,10 +91,10 @@ When SF detects a Claude Code model during startup, it automatically writes a `.
You can also trigger this manually from inside a SF session:
```bash
/gsd mcp init
/sf mcp init
```
This writes (or updates) the `gsd-workflow` entry in your project's `.mcp.json`. Claude Code discovers this file automatically on its next session start.
This writes (or updates) the `sf-workflow` entry in your project's `.mcp.json`. Claude Code discovers this file automatically on its next session start.
**Manual setup:**
@ -103,24 +103,24 @@ If you prefer to configure it yourself, add SF to your project's `.mcp.json`:
```json
{
"mcpServers": {
"gsd": {
"sf": {
"command": "npx",
"args": ["gsd-mcp-server"],
"args": ["sf-mcp-server"],
"env": {
"SF_CLI_PATH": "/path/to/gsd"
"SF_CLI_PATH": "/path/to/sf"
}
}
}
}
```
Or if `gsd-mcp-server` is installed globally:
Or if `sf-mcp-server` is installed globally:
```json
{
"mcpServers": {
"gsd": {
"command": "gsd-mcp-server"
"sf": {
"command": "sf-mcp-server"
}
}
}
@ -137,7 +137,7 @@ The MCP server provides SF's full workflow tool surface — milestone planning,
From inside a SF session, check that the MCP server is reachable:
```bash
/gsd mcp status
/sf mcp status
```
### OpenAI
@ -146,7 +146,7 @@ From inside a SF session, check that the MCP server is reachable:
export OPENAI_API_KEY="sk-..."
```
Or run `gsd config` and choose "Paste an API key" then "OpenAI".
Or run `sf config` and choose "Paste an API key" then "OpenAI".
**Get a key:** [platform.openai.com/api-keys](https://platform.openai.com/api-keys)
@ -172,7 +172,7 @@ Go to [openrouter.ai/keys](https://openrouter.ai/keys) and create a key.
export OPENROUTER_API_KEY="sk-or-..."
```
Or run `gsd config`, choose "Paste an API key", then "OpenRouter".
Or run `sf config`, choose "Paste an API key", then "OpenRouter".
**Step 3 — Switch to an OpenRouter model:**
@ -180,7 +180,7 @@ Inside a SF session, type `/model` and select an OpenRouter model. Models are pr
**Optional — Add custom OpenRouter models via `models.json`:**
If you want models not in the built-in list, add them to `~/.gsd/agent/models.json`:
If you want models not in the built-in list, add them to `~/.sf/agent/models.json`:
```json
{
@ -258,7 +258,7 @@ export MISTRAL_API_KEY="..."
Uses OAuth — sign in through the browser:
```bash
gsd config
sf config
# Choose "Sign in with your browser" → "GitHub Copilot"
```
@ -306,7 +306,7 @@ export AZURE_OPENAI_API_KEY="..."
Local providers run on your machine. They require a `models.json` configuration file because SF needs to know the endpoint URL and which models are available.
**Config file location:** `~/.gsd/agent/models.json`
**Config file location:** `~/.sf/agent/models.json`
The file reloads each time you open `/model` — no restart needed.
@ -329,7 +329,7 @@ ollama pull llama3.1:8b
ollama pull qwen2.5-coder:7b
```
**Step 3 — Create `~/.gsd/agent/models.json`:**
**Step 3 — Create `~/.sf/agent/models.json`:**
```json
{
@ -372,7 +372,7 @@ Download from [lmstudio.ai](https://lmstudio.ai).
In LM Studio, go to the "Local Server" tab, load a model, and click "Start Server". The default port is 1234.
**Step 3 — Create `~/.gsd/agent/models.json`:**
**Step 3 — Create `~/.sf/agent/models.json`:**
```json
{
@ -465,12 +465,12 @@ Any server that implements the OpenAI Chat Completions API can work with SF. Thi
**Quickest path — use the onboarding wizard:**
```bash
gsd config
sf config
# Choose "Paste an API key" → "Custom (OpenAI-compatible)"
# Enter: base URL, API key, model ID
```
This writes `~/.gsd/agent/models.json` for you automatically.
This writes `~/.sf/agent/models.json` for you automatically.
**Manual setup:**
@ -540,7 +540,7 @@ For the full reference on `compat` fields, `modelOverrides`, value resolution, a
**Cause:** The key is set in your shell but not visible to SF.
**Fix:** Make sure the environment variable is exported in the same terminal where you run `gsd`. Or use `gsd config` to save the key to `~/.gsd/agent/auth.json` so it persists across sessions.
**Fix:** Make sure the environment variable is exported in the same terminal where you run `sf`. Or use `sf config` to save the key to `~/.sf/agent/auth.json` so it persists across sessions.
### OpenRouter models not appearing in `/model`
@ -550,7 +550,7 @@ For the full reference on `compat` fields, `modelOverrides`, value resolution, a
```bash
export OPENROUTER_API_KEY="sk-or-..."
gsd
sf
```
### Ollama returns empty responses
@ -630,7 +630,7 @@ After configuring a provider:
1. **Launch SF:**
```bash
gsd
sf
```
2. **Check available models:**
@ -647,7 +647,7 @@ After configuring a provider:
If the model doesn't appear, check:
- The environment variable is set in the current shell
- `models.json` is valid JSON (use `cat ~/.gsd/agent/models.json | python3 -m json.tool`)
- `models.json` is valid JSON (use `cat ~/.sf/agent/models.json | python3 -m json.tool`)
- The server is running (for local providers)
For additional help, see [Troubleshooting](./troubleshooting.md) or run `/gsd doctor` inside a session.
For additional help, see [Troubleshooting](./troubleshooting.md) or run `/sf doctor` inside a session.

20
docs/user-docs/remote-questions.md
View file

@ -7,7 +7,7 @@ Remote questions allow SF to ask for user input via Slack, Discord, or Telegram
### Discord
```
/gsd remote discord
/sf remote discord
```
The setup wizard:
@ -16,7 +16,7 @@ The setup wizard:
3. Lists servers the bot belongs to (or lets you pick)
4. Lists text channels in the selected server
5. Sends a test message to confirm permissions
6. Saves the configuration to `~/.gsd/PREFERENCES.md`
6. Saves the configuration to `~/.sf/PREFERENCES.md`
**Bot requirements:**
- A Discord bot application with a token (from [Discord Developer Portal](https://discord.com/developers/applications))
@ -30,7 +30,7 @@ The setup wizard:
### Slack
```
/gsd remote slack
/sf remote slack
```
The setup wizard:
@ -48,7 +48,7 @@ The setup wizard:
### Telegram
```
/gsd remote telegram
/sf remote telegram
```
The setup wizard:
@ -65,7 +65,7 @@ The setup wizard:
## Configuration
Remote questions are configured in `~/.gsd/PREFERENCES.md`:
Remote questions are configured in `~/.sf/PREFERENCES.md`:
```yaml
remote_questions:
@ -105,11 +105,11 @@ If no response is received within `timeout_minutes`, the prompt times out and SF
| Command | Description |
|---------|-------------|
| `/gsd remote` | Show remote questions menu and current status |
| `/gsd remote slack` | Set up Slack integration |
| `/gsd remote discord` | Set up Discord integration |
| `/gsd remote status` | Show current configuration and last prompt status |
| `/gsd remote disconnect` | Remove remote questions configuration |
| `/sf remote` | Show remote questions menu and current status |
| `/sf remote slack` | Set up Slack integration |
| `/sf remote discord` | Set up Discord integration |
| `/sf remote status` | Show current configuration and last prompt status |
| `/sf remote disconnect` | Remove remote questions configuration |
## Discord vs Slack Feature Comparison

20
docs/user-docs/skills.md
View file

@ -15,7 +15,7 @@ SF reads skills from two locations, in priority order:
Global skills take precedence over project skills when names collide.
> **Migration from `~/.gsd/agent/skills/`:** On first launch after upgrading, SF automatically copies skills from the legacy `~/.gsd/agent/skills/` directory to `~/.agents/skills/`. The old directory is preserved for backward compatibility.
> **Migration from `~/.sf/agent/skills/`:** On first launch after upgrading, SF automatically copies skills from the legacy `~/.sf/agent/skills/` directory to `~/.agents/skills/`. The old directory is preserved for backward compatibility.
## Installing Skills
@ -40,9 +40,9 @@ npx skills update
### Onboarding Catalog
During `gsd init`, SF detects the project's tech stack and recommends relevant skill packs. For brownfield projects, detection is automatic; for greenfield projects, the user picks a tech stack.
During `sf init`, SF detects the project's tech stack and recommends relevant skill packs. For brownfield projects, detection is automatic; for greenfield projects, the user picks a tech stack.
The curated catalog is maintained in `src/resources/extensions/gsd/skill-catalog.ts`. Each entry maps a tech stack to a skills.sh repo and specific skill names.
The curated catalog is maintained in `src/resources/extensions/sf/skill-catalog.ts`. Each entry maps a tech stack to a skills.sh repo and specific skill names.
#### Available Skill Packs
@ -73,7 +73,7 @@ The curated catalog is maintained in `src/resources/extensions/gsd/skill-catalog
### Maintaining the Catalog
The skill catalog lives in [`src/resources/extensions/gsd/skill-catalog.ts`](../src/resources/extensions/gsd/skill-catalog.ts). To add or update a pack:
The skill catalog lives in [`src/resources/extensions/sf/skill-catalog.ts`](../src/resources/extensions/sf/skill-catalog.ts). To add or update a pack:
1. Add a `SkillPack` entry to the `SKILL_CATALOG` array with `repo`, `skills`, and matching criteria
2. For language-detection matching, use `matchLanguages` (values from `detection.ts` `LANGUAGE_MAP`)
@ -155,13 +155,13 @@ Every auto-mode unit records which skills were available and actively loaded. Th
### Skill Health Dashboard
View skill performance with `/gsd skill-health`:
View skill performance with `/sf skill-health`:
```
/gsd skill-health # overview table: name, uses, success%, tokens, trend, last used
/gsd skill-health rust-core # detailed view for one skill
/gsd skill-health --stale 30 # skills unused for 30+ days
/gsd skill-health --declining # skills with falling success rates
/sf skill-health # overview table: name, uses, success%, tokens, trend, last used
/sf skill-health rust-core # detailed view for one skill
/sf skill-health --stale 30 # skills unused for 30+ days
/sf skill-health --declining # skills with falling success rates
```
The dashboard flags skills that may need attention:
@ -183,6 +183,6 @@ Stale skills are excluded from automatic matching but remain invokable explicitl
### Heal-Skill (Post-Unit Analysis)
When configured as a post-unit hook, SF can analyze whether the agent deviated from a skill's instructions during execution. If significant drift is detected (outdated API patterns, incorrect guidance), it writes proposed fixes to `.gsd/skill-review-queue.md` for human review.
When configured as a post-unit hook, SF can analyze whether the agent deviated from a skill's instructions during execution. If significant drift is detected (outdated API patterns, incorrect guidance), it writes proposed fixes to `.sf/skill-review-queue.md` for human review.
Key design principle: skills are **never auto-modified**. Research shows curated skills outperform auto-generated ones significantly, so the human review step is critical.

14
docs/user-docs/token-optimization.md
View file

@ -165,7 +165,7 @@ This graduated approach preserves model quality for the most complex work while
## Adaptive Learning (Routing History)
SF tracks the success and failure of each tier assignment over time and adjusts future classifications accordingly. This is opt-in — it happens automatically and persists in `.gsd/routing-history.json`.
SF tracks the success and failure of each tier assignment over time and adjusts future classifications accordingly. This is opt-in — it happens automatically and persists in `.sf/routing-history.json`.
### How It Works
@ -176,12 +176,12 @@ SF tracks the success and failure of each tier assignment over time and adjusts
### User Feedback
Use `/gsd rate` to submit feedback on the last completed unit's model tier:
Use `/sf rate` to submit feedback on the last completed unit's model tier:
```
/gsd rate over # model was overpowered — encourage cheaper next time
/gsd rate ok # model was appropriate — no adjustment
/gsd rate under # model was too weak — encourage stronger next time
/sf rate over # model was overpowered — encourage cheaper next time
/sf rate ok # model was appropriate — no adjustment
/sf rate under # model was too weak — encourage stronger next time
```
Feedback signals are weighted 2× compared to automatic outcomes. Requires dynamic routing to be active (the last unit must have tier data).
@ -190,7 +190,7 @@ Feedback signals are weighted 2× compared to automatic outcomes. Requires dynam
```bash
# Routing history is stored per-project
.gsd/routing-history.json
.sf/routing-history.json
# Clear history to reset adaptive learning
# (happens via the routing-history module API)
@ -309,7 +309,7 @@ Individual tool results that exceed `tool_result_max_chars` (default: 800) are t
*Introduced in v2.59.0*
When auto-mode transitions between phases (research → planning → execution), structured JSON anchors are written to `.gsd/milestones/<mid>/anchors/<phase>.json`. Downstream prompt builders inject these anchors so the next phase inherits intent, decisions, blockers, and next steps without re-inferring from artifact files.
When auto-mode transitions between phases (research → planning → execution), structured JSON anchors are written to `.sf/milestones/<mid>/anchors/<phase>.json`. Downstream prompt builders inject these anchors so the next phase inherits intent, decisions, blockers, and next steps without re-inferring from artifact files.
This reduces context drift — the 65% of enterprise agent failures caused by agents losing track of prior decisions across phase boundaries.

80
docs/user-docs/troubleshooting.md
View file

@ -1,11 +1,11 @@
# Troubleshooting
## `/gsd doctor`
## `/sf doctor`
The built-in diagnostic tool validates `.gsd/` integrity:
The built-in diagnostic tool validates `.sf/` integrity:
```
/gsd doctor
/sf doctor
```
It checks:
@ -25,13 +25,13 @@ It checks:
- Stale cache after a crash — the in-memory file listing doesn't reflect new artifacts
- The LLM didn't produce the expected artifact file
**Fix:** Run `/gsd doctor` to repair state, then resume with `/gsd auto`. If the issue persists, check that the expected artifact file exists on disk.
**Fix:** Run `/sf doctor` to repair state, then resume with `/sf auto`. If the issue persists, check that the expected artifact file exists on disk.
### Auto mode stops with "Loop detected"
**Cause:** A unit failed to produce its expected artifact twice in a row.
**Fix:** Check the task plan for clarity. If the plan is ambiguous, refine it manually, then `/gsd auto` to resume.
**Fix:** Check the task plan for clarity. If the plan is ambiguous, refine it manually, then `/sf auto` to resume.
### Wrong files in worktree
@ -41,9 +41,9 @@ It checks:
**Fix:** This was fixed in v2.14+. If you're on an older version, update. The dispatch prompt now includes explicit working directory instructions.
### `command not found: gsd` after install
### `command not found: sf` after install
**Symptoms:** `npm install -g sf-run` succeeds but `gsd` isn't found.
**Symptoms:** `npm install -g sf-run` succeeds but `sf` isn't found.
**Cause:** npm's global bin directory isn't in your shell's `$PATH`.
@ -59,12 +59,12 @@ echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```
**Workaround:** Run `npx sf-run` or `$(npm prefix -g)/bin/gsd` directly.
**Workaround:** Run `npx sf-run` or `$(npm prefix -g)/bin/sf` directly.
**Common causes:**
- **Homebrew Node** — `/opt/homebrew/bin` should be in PATH but sometimes isn't if Homebrew init is missing from your shell profile
- **Version manager (nvm, fnm, mise)** — global bin is version-specific; ensure your version manager initializes in your shell config
- **oh-my-zsh** — the `gitfast` plugin aliases `gsd` to `git svn dcommit`. Check with `alias gsd` and unalias if needed
- **oh-my-zsh** — the `gitfast` plugin aliases `sf` to `git svn dcommit`. Check with `alias sf` and unalias if needed
### `npm install -g sf-run` fails
@ -95,7 +95,7 @@ models:
- openrouter/minimax/minimax-m2.5
```
**Headless mode:** `gsd headless auto` auto-restarts the entire process on crash (default 3 attempts with exponential backoff). Combined with provider error auto-resume, this enables true overnight unattended execution.
**Headless mode:** `sf headless auto` auto-restarts the entire process on crash (default 3 attempts with exponential backoff). Combined with provider error auto-resume, this enables true overnight unattended execution.
For common provider setup issues (role errors, streaming errors, model ID mismatches), see the [Provider Setup Guide — Common Pitfalls](./providers.md#common-pitfalls).
@ -103,46 +103,46 @@ For common provider setup issues (role errors, streaming errors, model ID mismat
**Symptoms:** Auto mode pauses with "Budget ceiling reached."
**Fix:** Increase `budget_ceiling` in preferences, or switch to `budget` token profile to reduce per-unit cost, then resume with `/gsd auto`.
**Fix:** Increase `budget_ceiling` in preferences, or switch to `budget` token profile to reduce per-unit cost, then resume with `/sf auto`.
### Stale lock file
**Symptoms:** Auto mode won't start, says another session is running.
**Fix:** SF automatically detects stale locks — if the owning PID is dead, the lock is cleaned up and re-acquired on the next `/gsd auto`. This includes stranded `.gsd.lock/` directories left by `proper-lockfile` after crashes. If automatic recovery fails, delete `.gsd/auto.lock` and the `.gsd.lock/` directory manually:
**Fix:** SF automatically detects stale locks — if the owning PID is dead, the lock is cleaned up and re-acquired on the next `/sf auto`. This includes stranded `.sf.lock/` directories left by `proper-lockfile` after crashes. If automatic recovery fails, delete `.sf/auto.lock` and the `.sf.lock/` directory manually:
```bash
rm -f .gsd/auto.lock
rm -rf "$(dirname .gsd)/.gsd.lock"
rm -f .sf/auto.lock
rm -rf "$(dirname .sf)/.sf.lock"
```
### Git merge conflicts
**Symptoms:** Worktree merge fails on `.gsd/` files.
**Symptoms:** Worktree merge fails on `.sf/` files.
**Fix:** SF auto-resolves conflicts on `.gsd/` runtime files. For content conflicts in code files, the LLM is given an opportunity to resolve them via a fix-merge session. If that fails, manual resolution is needed.
**Fix:** SF auto-resolves conflicts on `.sf/` runtime files. For content conflicts in code files, the LLM is given an opportunity to resolve them via a fix-merge session. If that fails, manual resolution is needed.
### Pre-dispatch says the milestone integration branch no longer exists
**Symptoms:** Auto mode or `/gsd doctor` reports that a milestone recorded an integration branch that no longer exists in git.
**Symptoms:** Auto mode or `/sf doctor` reports that a milestone recorded an integration branch that no longer exists in git.
**What it means:** The milestone's `.gsd/milestones/<MID>/<MID>-META.json` still points at the branch that was active when the milestone started, but that branch has since been renamed or deleted.
**What it means:** The milestone's `.sf/milestones/<MID>/<MID>-META.json` still points at the branch that was active when the milestone started, but that branch has since been renamed or deleted.
**Current behavior:**
- If SF can deterministically recover to a safe branch, it no longer hard-stops auto mode.
- Safe fallbacks are:
- explicit `git.main_branch` when configured and present
- the repo's detected default integration branch (for example `main` or `master`)
- In that case `/gsd doctor` reports a warning and `/gsd doctor fix` rewrites the stale metadata to the effective branch.
- In that case `/sf doctor` reports a warning and `/sf doctor fix` rewrites the stale metadata to the effective branch.
- SF still blocks when no safe fallback branch can be determined.
**Fix:**
- Run `/gsd doctor fix` to rewrite the stale milestone metadata automatically when the fallback is obvious.
- Run `/sf doctor fix` to rewrite the stale milestone metadata automatically when the fallback is obvious.
- If SF still blocks, recreate the missing branch or update your git preferences so `git.main_branch` points at a real branch.
### Transient `EBUSY` / `EPERM` / `EACCES` while writing `.gsd/` files
### Transient `EBUSY` / `EPERM` / `EACCES` while writing `.sf/` files
**Symptoms:** On Windows, auto mode or doctor occasionally fails while updating `.gsd/` files with errors like `EBUSY`, `EPERM`, or `EACCES`.
**Symptoms:** On Windows, auto mode or doctor occasionally fails while updating `.sf/` files with errors like `EBUSY`, `EPERM`, or `EACCES`.
**Cause:** Antivirus, indexers, editors, or filesystem watchers can briefly lock the destination or temp file just as SF performs the atomic rename.
@ -151,11 +151,11 @@ rm -rf "$(dirname .gsd)/.gsd.lock"
**Fix:**
- Re-run the operation; most transient lock races clear quickly.
- If the error persists, close tools that may be holding the file open and then retry.
- If repeated failures continue, run `/gsd doctor` to confirm the repo state is still healthy and report the exact path + error code.
- If repeated failures continue, run `/sf doctor` to confirm the repo state is still healthy and report the exact path + error code.
### Node v24 web boot failure
**Symptoms:** `gsd --web` fails with `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING` on Node v24.
**Symptoms:** `sf --web` fails with `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING` on Node v24.
**Cause:** Node v24 changed type-stripping behavior for `node_modules`, breaking the Next.js web build.
@ -163,7 +163,7 @@ rm -rf "$(dirname .gsd)/.gsd.lock"
### Orphan web server process
**Symptoms:** `gsd --web` fails because port 3000 is already in use, even though no SF session is running.
**Symptoms:** `sf --web` fails because port 3000 is already in use, even though no SF session is running.
**Cause:** A previous web server process was not cleaned up on exit.
@ -192,12 +192,12 @@ rm -rf "$(dirname .gsd)/.gsd.lock"
**Symptoms:** `mcp_servers` reports no servers configured.
**Common causes:**
- No `.mcp.json` or `.gsd/mcp.json` file exists in the current project
- No `.mcp.json` or `.sf/mcp.json` file exists in the current project
- The config file is malformed JSON
- The server is configured in a different project directory than the one where you launched SF
**Fix:**
- Add the server to `.mcp.json` or `.gsd/mcp.json`
- Add the server to `.mcp.json` or `.sf/mcp.json`
- Verify the file parses as JSON
- Re-run `mcp_servers(refresh=true)`
@ -258,11 +258,11 @@ rm -rf "$(dirname .gsd)/.gsd.lock"
- Set required environment variables in the MCP config's `env` block
- If needed, set `cwd` explicitly in the server definition
### Session lock stolen by `/gsd` in another terminal
### Session lock stolen by `/sf` in another terminal
**Symptoms:** Running `/gsd` (step mode) in a second terminal causes a running auto-mode session to lose its lock.
**Symptoms:** Running `/sf` (step mode) in a second terminal causes a running auto-mode session to lose its lock.
**Fix:** Fixed in v2.36.0. Bare `/gsd` no longer steals the session lock from a running auto-mode session. Upgrade to the latest version.
**Fix:** Fixed in v2.36.0. Bare `/sf` no longer steals the session lock from a running auto-mode session. Upgrade to the latest version.
### Worktree commits landing on main instead of milestone branch
@ -283,34 +283,34 @@ rm -rf "$(dirname .gsd)/.gsd.lock"
### Reset auto mode state
```bash
rm .gsd/auto.lock
rm .gsd/completed-units.json
rm .sf/auto.lock
rm .sf/completed-units.json
```
Then `/gsd auto` to restart from current disk state.
Then `/sf auto` to restart from current disk state.
### Reset routing history
If adaptive model routing is producing bad results, clear the routing history:
```bash
rm .gsd/routing-history.json
rm .sf/routing-history.json
```
### Full state rebuild
```
/gsd doctor
/sf doctor
```
Doctor rebuilds `STATE.md` from plan and roadmap files on disk and fixes detected inconsistencies.
## Getting Help
- **GitHub Issues:** [github.com/gsd-build/SF/issues](https://github.com/gsd-build/SF/issues)
- **Dashboard:** `Ctrl+Alt+G` or `/gsd status` for real-time diagnostics
- **Forensics:** `/gsd forensics` for structured post-mortem analysis of auto-mode failures
- **Session logs:** `.gsd/activity/` contains JSONL session dumps for crash forensics
- **GitHub Issues:** [github.com/sf-build/SF/issues](https://github.com/sf-build/SF/issues)
- **Dashboard:** `Ctrl+Alt+G` or `/sf status` for real-time diagnostics
- **Forensics:** `/sf forensics` for structured post-mortem analysis of auto-mode failures
- **Session logs:** `.sf/activity/` contains JSONL session dumps for crash forensics
## iTerm2-Specific Issues
@ -346,7 +346,7 @@ Doctor rebuilds `STATE.md` from plan and roadmap files on disk and fixes detecte
**Symptoms:** `gsd_decision_save` (or its alias `gsd_save_decision`), `gsd_requirement_update` (or `gsd_update_requirement`), or `gsd_summary_save` (or `gsd_save_summary`) fail with this error.
**Cause:** The SQLite database wasn't initialized. This happens in manual `/gsd` sessions (non-auto mode) on versions before v2.29.
**Cause:** The SQLite database wasn't initialized. This happens in manual `/sf` sessions (non-auto mode) on versions before v2.29.
**Fix:** Updated in v2.29+ to auto-initialize the database on first tool call. Upgrade to the latest version.

6
docs/user-docs/visualizer.md
View file

@ -7,7 +7,7 @@ The workflow visualizer is a full-screen TUI overlay that shows project progress
## Opening the Visualizer
```
/gsd visualize
/sf visualize
```
Or configure automatic display after milestone completion:
@ -59,7 +59,7 @@ Bar charts showing cost and token usage breakdowns:
- **By slice** — cost per slice with running totals
- **By model** — which models consumed the most budget
Uses data from `.gsd/metrics.json`.
Uses data from `.sf/metrics.json`.
### 4. Timeline
@ -89,7 +89,7 @@ The visualizer refreshes data from disk every 2 seconds, so it stays current if
## HTML Export (v2.26)
For shareable reports outside the terminal, use `/gsd export --html`. This generates a self-contained HTML file in `.gsd/reports/` with the same data as the TUI visualizer — progress tree, dependency graph (SVG DAG), cost/token bar charts, execution timeline, changelog, and knowledge base. All CSS and JS are inlined — no external dependencies. Printable to PDF from any browser.
For shareable reports outside the terminal, use `/sf export --html`. This generates a self-contained HTML file in `.sf/reports/` with the same data as the TUI visualizer — progress tree, dependency graph (SVG DAG), cost/token bar charts, execution timeline, changelog, and knowledge base. All CSS and JS are inlined — no external dependencies. Printable to PDF from any browser.
An auto-generated `index.html` shows all reports with progression metrics across milestones.

4
docs/user-docs/web-interface.md
View file

@ -7,7 +7,7 @@ SF includes a browser-based web interface for project management, real-time prog
## Quick Start
```bash
gsd --web
sf --web
```
This starts a local web server and opens the SF dashboard in your default browser.
@ -15,7 +15,7 @@ This starts a local web server and opens the SF dashboard in your default browse
### CLI Flags (v2.42.0)
```bash
gsd --web --host 0.0.0.0 --port 8080 --allowed-origins "https://example.com"
sf --web --host 0.0.0.0 --port 8080 --allowed-origins "https://example.com"
```
| Flag | Default | Description |

42
docs/user-docs/working-in-teams.md
View file

@ -9,7 +9,7 @@ SF supports multi-user workflows where several developers work on the same repos
The simplest way to configure SF for team use is to set `mode: team` in your project preferences. This enables unique milestone IDs, push branches, and pre-merge checks in one setting:
```yaml
# .gsd/PREFERENCES.md (project-level, committed to git)
# .sf/PREFERENCES.md (project-level, committed to git)
---
version: 1
mode: team
@ -26,23 +26,23 @@ Share planning artifacts (milestones, roadmaps, decisions) while keeping runtime
```bash
# ── SF: Runtime / Ephemeral (per-developer, per-session) ──────
.gsd/auto.lock
.gsd/completed-units.json
.gsd/STATE.md
.gsd/metrics.json
.gsd/activity/
.gsd/runtime/
.gsd/worktrees/
.gsd/milestones/**/continue.md
.gsd/milestones/**/*-CONTINUE.md
.sf/auto.lock
.sf/completed-units.json
.sf/STATE.md
.sf/metrics.json
.sf/activity/
.sf/runtime/
.sf/worktrees/
.sf/milestones/**/continue.md
.sf/milestones/**/*-CONTINUE.md
```
**What gets shared** (committed to git):
- `.gsd/PREFERENCES.md` — project preferences
- `.gsd/PROJECT.md` — living project description
- `.gsd/REQUIREMENTS.md` — requirement contract
- `.gsd/DECISIONS.md` — architectural decisions
- `.gsd/milestones/` — roadmaps, plans, summaries, research
- `.sf/PREFERENCES.md` — project preferences
- `.sf/PROJECT.md` — living project description
- `.sf/REQUIREMENTS.md` — requirement contract
- `.sf/DECISIONS.md` — architectural decisions
- `.sf/milestones/` — roadmaps, plans, summaries, research
**What stays local** (gitignored):
- Lock files, metrics, state cache, runtime records, worktrees, activity logs
@ -50,7 +50,7 @@ Share planning artifacts (milestones, roadmaps, decisions) while keeping runtime
### 3. Commit the Preferences
```bash
git add .gsd/PREFERENCES.md
git add .sf/PREFERENCES.md
git commit -m "chore: enable SF team workflow"
```
@ -63,21 +63,21 @@ git:
commit_docs: false
```
This adds `.gsd/` to `.gitignore` entirely and keeps all artifacts local. The developer gets the benefits of structured planning without affecting teammates who don't use SF.
This adds `.sf/` to `.gitignore` entirely and keeps all artifacts local. The developer gets the benefits of structured planning without affecting teammates who don't use SF.
## Migrating an Existing Project
If you have an existing project with `.gsd/` blanket-ignored:
If you have an existing project with `.sf/` blanket-ignored:
1. Ensure no milestones are in progress (clean state)
2. Update `.gitignore` to use the selective pattern above
3. Add `unique_milestone_ids: true` to `.gsd/PREFERENCES.md`
3. Add `unique_milestone_ids: true` to `.sf/PREFERENCES.md`
4. Optionally rename existing milestones to use unique IDs:
```
I have turned on unique milestone ids, please update all old milestone
ids to use this new format e.g. M001-abc123 where abc123 is a random
6 char lowercase alpha numeric string. Update all references in all
.gsd file contents, file names and directory names. Validate your work
.sf file contents, file names and directory names. Validate your work
once done to ensure referential integrity.
```
5. Commit
@ -86,7 +86,7 @@ If you have an existing project with `.gsd/` blanket-ignored:
Multiple developers can run auto mode simultaneously on different milestones. Each developer:
- Gets their own worktree (`.gsd/worktrees/<MID>/`, gitignored)
- Gets their own worktree (`.sf/worktrees/<MID>/`, gitignored)
- Works on a unique `milestone/<MID>` branch
- Squash-merges to main independently

6
docs/zh-CN/README.md
View file

@ -26,7 +26,7 @@
| [并行编排](./user-docs/parallel-orchestration.md) | 通过隔离的工作线程和协调机制同时运行多个 milestones |
| [团队协作](./user-docs/working-in-teams.md) | 唯一 milestone ID、`.gitignore` 设置和共享规划产物 |
| [技能](./user-docs/skills.md) | 内置技能、技能发现和自定义技能编写 |
| [从 v1 迁移](./user-docs/migration.md) | 将 `.planning` 目录迁移到新的 `.gsd` 格式 |
| [故障排查](./user-docs/troubleshooting.md) | 常见问题、`/gsd doctor`、`/gsd forensics` 和恢复流程 |
| [Web 界面](./user-docs/web-interface.md) | 通过 `gsd --web` 使用基于浏览器的项目管理界面 |
| [从 v1 迁移](./user-docs/migration.md) | 将 `.planning` 目录迁移到新的 `.sf` 格式 |
| [故障排查](./user-docs/troubleshooting.md) | 常见问题、`/sf doctor`、`/sf forensics` 和恢复流程 |
| [Web 界面](./user-docs/web-interface.md) | 通过 `sf --web` 使用基于浏览器的项目管理界面 |
| [VS Code 扩展](../../vscode-extension/README.md) | 聊天参与者、侧边栏仪表板以及 VS Code 的 RPC 集成 |

36
docs/zh-CN/user-docs/auto-mode.md
View file

@ -1,10 +1,10 @@
# 自动模式
自动模式是 SF 的自主执行引擎。运行 `/gsd auto`，然后离开；回来时你会看到已经构建好的软件，以及干净的 git 历史。
自动模式是 SF 的自主执行引擎。运行 `/sf auto`，然后离开；回来时你会看到已经构建好的软件，以及干净的 git 历史。
## 工作原理
自动模式本质上是一个**由磁盘文件驱动的状态机**。它会读取 `.gsd/STATE.md`，确定下一个工作单元，创建一个新的 agent 会话，把所有相关上下文预先内联到一个聚焦 prompt 中，再让 LLM 执行。LLM 完成后，自动模式会再次读取磁盘状态，并派发下一个工作单元。
自动模式本质上是一个**由磁盘文件驱动的状态机**。它会读取 `.sf/STATE.md`，确定下一个工作单元，创建一个新的 agent 会话，把所有相关上下文预先内联到一个聚焦 prompt 中，再让 LLM 执行。LLM 完成后，自动模式会再次读取磁盘状态，并派发下一个工作单元。
### 执行循环
@ -47,7 +47,7 @@ Plan (with integrated research) → Execute (per task) → Complete → Reassess
SF 支持三种 milestone 隔离模式（通过偏好设置中的 `git.isolation` 配置）：
- **`worktree`**（默认）：每个 milestone 都运行在 `.gsd/worktrees/<MID>/` 下自己的 git worktree 中，分支名为 `milestone/<MID>`。所有 slice 工作都顺序提交，不需要切分支，也不会在 milestone 内部产生合并冲突。milestone 完成后，再整体 squash merge 回主分支，形成一个干净提交。
- **`worktree`**（默认）：每个 milestone 都运行在 `.sf/worktrees/<MID>/` 下自己的 git worktree 中，分支名为 `milestone/<MID>`。所有 slice 工作都顺序提交，不需要切分支，也不会在 milestone 内部产生合并冲突。milestone 完成后，再整体 squash merge 回主分支，形成一个干净提交。
- **`branch`**：工作发生在项目根目录下的 `milestone/<MID>` 分支上。适合子模块较多、worktree 表现不佳的仓库。
- **`none`**：直接在当前分支工作。没有 worktree，也没有 milestone 分支。适合文件隔离会破坏开发工具的热重载场景。
@ -59,9 +59,9 @@ SF 支持三种 milestone 隔离模式（通过偏好设置中的 `git.isolation
### 崩溃恢复
自动模式会用锁文件跟踪当前工作单元。如果会话中途退出，下一次执行 `/gsd auto` 时，会读取残留的会话文件，从所有已经落盘的工具调用中综合生成一份恢复简报，然后带着完整上下文继续执行。
自动模式会用锁文件跟踪当前工作单元。如果会话中途退出，下一次执行 `/sf auto` 时，会读取残留的会话文件，从所有已经落盘的工具调用中综合生成一份恢复简报，然后带着完整上下文继续执行。
**Headless 自动重启（v2.26）：** 当运行 `gsd headless auto` 时，崩溃会触发带指数退避的自动重启（5s → 10s → 30s 上限，默认最多 3 次）。通过 `--max-restarts N` 配置。SIGINT/SIGTERM 不会触发重启。结合崩溃恢复机制，这让真正的“跑一夜直到完成”成为可能。
**Headless 自动重启（v2.26）：** 当运行 `sf headless auto` 时，崩溃会触发带指数退避的自动重启（5s → 10s → 30s 上限，默认最多 3 次）。通过 `--max-restarts N` 配置。SIGINT/SIGTERM 不会触发重启。结合崩溃恢复机制，这让真正的“跑一夜直到完成”成为可能。
### Provider 错误恢复
@ -95,16 +95,16 @@ SF 使用滑动窗口分析来检测卡死循环。它不只是简单地统计
### 事后取证（v2.40）
`/gsd forensics` 是一个面向自动模式失败分析的全访问 SF 调试器，提供：
`/sf forensics` 是一个面向自动模式失败分析的全访问 SF 调试器，提供：
- **异常检测**：对卡死循环、成本尖峰、超时、产物缺失和崩溃做结构化识别，并标注严重级别
- **单元追踪**：最近 10 次单元执行，包含错误细节和执行时长
- **指标分析**：成本、token 数量和执行时间拆分
- **Doctor 集成**：把 `/gsd doctor` 中的结构性健康问题一起纳入
- **Doctor 集成**：把 `/sf doctor` 中的结构性健康问题一起纳入
- **LLM 引导调查**：启动一个拥有完整工具访问权限的 agent 会话来调查根因
```
/gsd forensics [optional problem description]
/sf forensics [optional problem description]
```
更多诊断方式见 [故障排查](./troubleshooting.md)。
@ -164,13 +164,13 @@ require_slice_discussion: true
### HTML 报告（v2.26）
每当 milestone 完成后，SF 都会在 `.gsd/reports/` 中自动生成一个自包含的 HTML 报告。报告包括项目摘要、进度树、slice 依赖图（SVG DAG）、成本 / Token 柱状图、执行时间线、变更日志和知识库。没有外部依赖，所有 CSS 和 JS 都会内联。
每当 milestone 完成后，SF 都会在 `.sf/reports/` 中自动生成一个自包含的 HTML 报告。报告包括项目摘要、进度树、slice 依赖图（SVG DAG）、成本 / Token 柱状图、执行时间线、变更日志和知识库。没有外部依赖，所有 CSS 和 JS 都会内联。
```yaml
auto_report: true # 默认开启
```
你也可以随时手动执行 `/gsd export --html` 生成报告，或通过 `/gsd export --html --all`（v2.28）为所有 milestones 一次性生成报告。
你也可以随时手动执行 `/sf export --html` 生成报告，或通过 `/sf export --html --all`（v2.28）为所有 milestones 一次性生成报告。
### 故障恢复强化（v2.28）
@ -190,7 +190,7 @@ v2.28 通过多项机制强化了自动模式的可靠性：原子文件写入
### 实时健康可见性（v2.40）
`/gsd doctor` 发现的问题现在会实时出现在三个地方：
`/sf doctor` 发现的问题现在会实时出现在三个地方：
- **Dashboard widget**：健康指示器，显示问题数量和严重级别
- **Workflow visualizer**：状态面板中展示问题
@ -213,7 +213,7 @@ v2.28 通过多项机制强化了自动模式的可靠性：原子文件写入
### 启动
```
/gsd auto
/sf auto
```
### 暂停
@ -223,7 +223,7 @@ v2.28 通过多项机制强化了自动模式的可靠性：原子文件写入
### 恢复
```
/gsd auto
/sf auto
```
自动模式会读取磁盘状态，并从中断处继续。
@ -231,7 +231,7 @@ v2.28 通过多项机制强化了自动模式的可靠性：原子文件写入
### 停止
```
/gsd stop
/sf stop
```
优雅地停止自动模式。这个命令也可以从另一个终端执行。
@ -239,7 +239,7 @@ v2.28 通过多项机制强化了自动模式的可靠性：原子文件写入
### 引导
```
/gsd steer
/sf steer
```
在不中断流水线的情况下，强制修改计划文档。修改会在下一个阶段边界生效。
@ -247,7 +247,7 @@ v2.28 通过多项机制强化了自动模式的可靠性：原子文件写入
### 捕获
```
/gsd capture "add rate limiting to API endpoints"
/sf capture "add rate limiting to API endpoints"
```
随手记录想法，不打断当前执行。Captures 会在 tasks 之间自动 triage。详见 [捕获与分流](./captures-triage.md)。
@ -255,14 +255,14 @@ v2.28 通过多项机制强化了自动模式的可靠性：原子文件写入
### 可视化
```
/gsd visualize
/sf visualize
```
打开工作流可视化器，交互式查看进度、依赖、指标和时间线。详见 [工作流可视化器](./visualizer.md)。
## 仪表板
`Ctrl+Alt+G` 或 `/gsd status` 会显示实时进度：
`Ctrl+Alt+G` 或 `/sf status` 会显示实时进度：
- 当前 milestone、slice 和 task
- 自动模式的已运行时间和当前阶段

16
docs/zh-CN/user-docs/captures-triage.md
View file

@ -9,11 +9,11 @@ Captures 允许你在自动模式执行过程中随手记录想法，而不必
在自动模式运行期间（或任何时候）：
```
/gsd capture "add rate limiting to the API endpoints"
/gsd capture "the auth flow should support OAuth, not just JWT"
/sf capture "add rate limiting to the API endpoints"
/sf capture "the auth flow should support OAuth, not just JWT"
```
这些 capture 会追加到 `.gsd/CAPTURES.md`，并在 tasks 之间自动参与 triage。
这些 capture 会追加到 `.sf/CAPTURES.md`，并在 tasks 之间自动参与 triage。
## 工作原理
@ -23,7 +23,7 @@ Captures 允许你在自动模式执行过程中随手记录想法，而不必
capture → triage → confirm → resolve → resume
```
1. **Capture**：`/gsd capture "thought"` 会带着时间戳和唯一 ID 追加到 `.gsd/CAPTURES.md`
1. **Capture**：`/sf capture "thought"` 会带着时间戳和唯一 ID 追加到 `.sf/CAPTURES.md`
2. **Triage**：在 tasks 之间的自然衔接点（`handleAgentEnd` 中），SF 会检测待处理 capture 并进行分类
3. **Confirm**：向用户展示建议的处理方式，由用户确认或调整
4. **Resolve**：应用该处理方案（插入 task、触发重规划、延期等）
@ -56,7 +56,7 @@ LLM 会对每条 capture 进行分类并给出建议处理方案。会修改计
你也可以随时手动触发 triage：
```
/gsd triage
/sf triage
```
这在你积累了多条 capture，并希望在下一个自然间隙之前先处理掉它们时很有用。
@ -74,11 +74,11 @@ Capture 上下文会自动注入到：
## Worktree 感知
Captures 总是写回**原始项目根目录**下的 `.gsd/CAPTURES.md`，而不是 worktree 的本地副本。这样从 steering 终端记录的内容，也能被运行在 worktree 里的自动模式会话看到。
Captures 总是写回**原始项目根目录**下的 `.sf/CAPTURES.md`，而不是 worktree 的本地副本。这样从 steering 终端记录的内容，也能被运行在 worktree 里的自动模式会话看到。
## 命令
| 命令 | 说明 |
|------|------|
| `/gsd capture "text"` | 记录一个想法（单词时引号可省略） |
| `/gsd triage` | 手动触发待处理 captures 的 triage |
| `/sf capture "text"` | 记录一个想法（单词时引号可省略） |
| `/sf triage` | 手动触发待处理 captures 的 triage |

240
docs/zh-CN/user-docs/commands.md
View file

@ -4,78 +4,78 @@
| 命令 | 说明 |
|------|------|
| `/gsd` | Step mode：一次执行一个工作单元，并在每步之间暂停 |
| `/gsd next` | 显式 Step mode（与 `/gsd` 相同） |
| `/gsd auto` | 自动模式：research、plan、execute、commit，然后重复 |
| `/gsd quick` | 在不经过完整 planning 开销的情况下，执行一个带 SF 保证的 quick task（原子提交、状态跟踪） |
| `/gsd stop` | 优雅地停止自动模式 |
| `/gsd pause` | 暂停自动模式（保留状态，可用 `/gsd auto` 恢复） |
| `/gsd steer` | 在执行过程中强制修改 plan 文档 |
| `/gsd discuss` | 讨论架构和决策（可与自动模式并行使用） |
| `/gsd status` | 进度仪表板 |
| `/gsd widget` | 循环切换仪表板组件：full / small / min / off |
| `/gsd queue` | 给未来 milestones 排队和重排（自动模式中也安全） |
| `/gsd capture` | 随手记录一个想法，不打断当前流程（自动模式中可用） |
| `/gsd triage` | 手动触发待处理 captures 的 triage |
| `/gsd dispatch` | 直接派发一个指定阶段（research、plan、execute、complete、reassess、uat、replan） |
| `/gsd history` | 查看执行历史（支持 `--cost`、`--phase`、`--model` 过滤） |
| `/gsd forensics` | 全访问 SF 调试器：用于分析自动模式失败，支持结构化异常检测、单元追踪和 LLM 引导的根因分析 |
| `/gsd cleanup` | 清理 SF 状态文件和过期 worktrees |
| `/gsd visualize` | 打开工作流可视化器（进度、依赖、指标、时间线） |
| `/gsd export --html` | 为当前或已完成的 milestone 生成自包含 HTML 报告 |
| `/gsd export --html --all` | 一次性为所有 milestones 生成回顾报告 |
| `/gsd update` | 在会话内更新到最新版本 |
| `/gsd knowledge` | 添加持久化项目知识（规则、模式或经验） |
| `/gsd fast` | 为支持的模型切换 service tier（优先级 API 路由） |
| `/gsd rate` | 评价上一个单元所用模型层级（over / ok / under），帮助改进自适应路由 |
| `/gsd changelog` | 查看分类后的发行说明 |
| `/gsd logs` | 浏览活动日志、调试日志和指标 |
| `/gsd remote` | 控制远程自动模式 |
| `/gsd help` | 查看所有 SF 子命令的分类参考及说明 |
| `/sf` | Step mode：一次执行一个工作单元，并在每步之间暂停 |
| `/sf next` | 显式 Step mode（与 `/sf` 相同） |
| `/sf auto` | 自动模式：research、plan、execute、commit，然后重复 |
| `/sf quick` | 在不经过完整 planning 开销的情况下，执行一个带 SF 保证的 quick task（原子提交、状态跟踪） |
| `/sf stop` | 优雅地停止自动模式 |
| `/sf pause` | 暂停自动模式（保留状态，可用 `/sf auto` 恢复） |
| `/sf steer` | 在执行过程中强制修改 plan 文档 |
| `/sf discuss` | 讨论架构和决策（可与自动模式并行使用） |
| `/sf status` | 进度仪表板 |
| `/sf widget` | 循环切换仪表板组件：full / small / min / off |
| `/sf queue` | 给未来 milestones 排队和重排（自动模式中也安全） |
| `/sf capture` | 随手记录一个想法，不打断当前流程（自动模式中可用） |
| `/sf triage` | 手动触发待处理 captures 的 triage |
| `/sf dispatch` | 直接派发一个指定阶段（research、plan、execute、complete、reassess、uat、replan） |
| `/sf history` | 查看执行历史（支持 `--cost`、`--phase`、`--model` 过滤） |
| `/sf forensics` | 全访问 SF 调试器：用于分析自动模式失败，支持结构化异常检测、单元追踪和 LLM 引导的根因分析 |
| `/sf cleanup` | 清理 SF 状态文件和过期 worktrees |
| `/sf visualize` | 打开工作流可视化器（进度、依赖、指标、时间线） |
| `/sf export --html` | 为当前或已完成的 milestone 生成自包含 HTML 报告 |
| `/sf export --html --all` | 一次性为所有 milestones 生成回顾报告 |
| `/sf update` | 在会话内更新到最新版本 |
| `/sf knowledge` | 添加持久化项目知识（规则、模式或经验） |
| `/sf fast` | 为支持的模型切换 service tier（优先级 API 路由） |
| `/sf rate` | 评价上一个单元所用模型层级（over / ok / under），帮助改进自适应路由 |
| `/sf changelog` | 查看分类后的发行说明 |
| `/sf logs` | 浏览活动日志、调试日志和指标 |
| `/sf remote` | 控制远程自动模式 |
| `/sf help` | 查看所有 SF 子命令的分类参考及说明 |
## 配置与诊断
| 命令 | 说明 |
|------|------|
| `/gsd prefs` | 模型选择、超时和预算上限 |
| `/gsd mode` | 切换工作流模式（solo / team），同时应用与 milestone ID、git 提交行为和文档相关的协调默认值 |
| `/gsd config` | 重新运行 provider 配置向导（LLM provider + 工具 key） |
| `/gsd keys` | API key 管理器：列出、添加、移除、测试、轮换、doctor |
| `/gsd doctor` | 运行时健康检查与自动修复；问题会实时显示在 widget、visualizer 和 HTML reports 中（v2.40） |
| `/gsd inspect` | 查看 SQLite DB 诊断信息 |
| `/gsd init` | 项目初始化向导：检测、配置并 bootstrap `.gsd/` |
| `/gsd setup` | 查看全局 setup 状态和配置 |
| `/gsd skill-health` | 技能生命周期仪表板：使用统计、成功率、token 趋势、过期告警 |
| `/gsd skill-health <name>` | 查看某个 skill 的详细信息 |
| `/gsd skill-health --declining` | 只显示被标记为表现下降的 skills |
| `/gsd skill-health --stale N` | 显示 N 天以上未使用的 skills |
| `/gsd hooks` | 查看已配置的 post-unit 和 pre-dispatch hooks |
| `/gsd run-hook` | 手动触发一个指定 hook |
| `/gsd migrate` | 将 v1 的 `.planning` 目录迁移到 `.gsd` 格式 |
| `/sf prefs` | 模型选择、超时和预算上限 |
| `/sf mode` | 切换工作流模式（solo / team），同时应用与 milestone ID、git 提交行为和文档相关的协调默认值 |
| `/sf config` | 重新运行 provider 配置向导（LLM provider + 工具 key） |
| `/sf keys` | API key 管理器：列出、添加、移除、测试、轮换、doctor |
| `/sf doctor` | 运行时健康检查与自动修复；问题会实时显示在 widget、visualizer 和 HTML reports 中（v2.40） |
| `/sf inspect` | 查看 SQLite DB 诊断信息 |
| `/sf init` | 项目初始化向导：检测、配置并 bootstrap `.sf/` |
| `/sf setup` | 查看全局 setup 状态和配置 |
| `/sf skill-health` | 技能生命周期仪表板：使用统计、成功率、token 趋势、过期告警 |
| `/sf skill-health <name>` | 查看某个 skill 的详细信息 |
| `/sf skill-health --declining` | 只显示被标记为表现下降的 skills |
| `/sf skill-health --stale N` | 显示 N 天以上未使用的 skills |
| `/sf hooks` | 查看已配置的 post-unit 和 pre-dispatch hooks |
| `/sf run-hook` | 手动触发一个指定 hook |
| `/sf migrate` | 将 v1 的 `.planning` 目录迁移到 `.sf` 格式 |
## Milestone 管理
| 命令 | 说明 |
|------|------|
| `/gsd new-milestone` | 创建一个新的 milestone |
| `/gsd skip` | 阻止某个工作单元被自动模式派发 |
| `/gsd undo` | 回退上一个已完成单元 |
| `/gsd undo-task` | 重置某个特定 task 的完成状态（DB + markdown） |
| `/gsd reset-slice` | 重置某个 slice 及其所有 tasks（DB + markdown） |
| `/gsd park` | Park 一个 milestone，不删除，只跳过 |
| `/gsd unpark` | 重新激活一个已 park 的 milestone |
| Discard milestone | 在 `/gsd` 向导的 “Milestone actions” → “Discard” 中可用 |
| `/sf new-milestone` | 创建一个新的 milestone |
| `/sf skip` | 阻止某个工作单元被自动模式派发 |
| `/sf undo` | 回退上一个已完成单元 |
| `/sf undo-task` | 重置某个特定 task 的完成状态（DB + markdown） |
| `/sf reset-slice` | 重置某个 slice 及其所有 tasks（DB + markdown） |
| `/sf park` | Park 一个 milestone，不删除，只跳过 |
| `/sf unpark` | 重新激活一个已 park 的 milestone |
| Discard milestone | 在 `/sf` 向导的 “Milestone actions” → “Discard” 中可用 |
## 并行编排
| 命令 | 说明 |
|------|------|
| `/gsd parallel start` | 分析可并行性、确认后启动 workers |
| `/gsd parallel status` | 显示所有 workers 的状态、进度和成本 |
| `/gsd parallel stop [MID]` | 停止所有 workers，或停止某个指定 milestone 的 worker |
| `/gsd parallel pause [MID]` | 暂停所有 workers，或暂停某个指定 worker |
| `/gsd parallel resume [MID]` | 恢复已暂停的 workers |
| `/gsd parallel merge [MID]` | 把已完成的 milestones 合并回 main |
| `/sf parallel start` | 分析可并行性、确认后启动 workers |
| `/sf parallel status` | 显示所有 workers 的状态、进度和成本 |
| `/sf parallel stop [MID]` | 停止所有 workers，或停止某个指定 milestone 的 worker |
| `/sf parallel pause [MID]` | 暂停所有 workers，或暂停某个指定 worker |
| `/sf parallel resume [MID]` | 恢复已暂停的 workers |
| `/sf parallel merge [MID]` | 把已完成的 milestones 合并回 main |
完整文档见 [并行编排](./parallel-orchestration.md)。
@ -83,50 +83,50 @@
| 命令 | 说明 |
|------|------|
| `/gsd start` | 启动一个 workflow template（bugfix、spike、feature、hotfix、refactor、security-audit、dep-upgrade、full-project） |
| `/gsd start resume` | 恢复一个进行中的 workflow |
| `/gsd templates` | 列出可用 workflow templates |
| `/gsd templates info <name>` | 查看某个 template 的详细信息 |
| `/sf start` | 启动一个 workflow template（bugfix、spike、feature、hotfix、refactor、security-audit、dep-upgrade、full-project） |
| `/sf start resume` | 恢复一个进行中的 workflow |
| `/sf templates` | 列出可用 workflow templates |
| `/sf templates info <name>` | 查看某个 template 的详细信息 |
## 自定义 Workflows（v2.42）
| 命令 | 说明 |
|------|------|
| `/gsd workflow new` | 创建一个新的 workflow definition（通过 skill） |
| `/gsd workflow run <name>` | 创建一个 run 并启动自动模式 |
| `/gsd workflow list` | 列出 workflow runs |
| `/gsd workflow validate <name>` | 校验一个 workflow YAML definition |
| `/gsd workflow pause` | 暂停自定义 workflow 的自动模式 |
| `/gsd workflow resume` | 恢复已暂停的自定义 workflow 自动模式 |
| `/sf workflow new` | 创建一个新的 workflow definition（通过 skill） |
| `/sf workflow run <name>` | 创建一个 run 并启动自动模式 |
| `/sf workflow list` | 列出 workflow runs |
| `/sf workflow validate <name>` | 校验一个 workflow YAML definition |
| `/sf workflow pause` | 暂停自定义 workflow 的自动模式 |
| `/sf workflow resume` | 恢复已暂停的自定义 workflow 自动模式 |
## 扩展
| 命令 | 说明 |
|------|------|
| `/gsd extensions list` | 列出所有扩展及其状态 |
| `/gsd extensions enable <id>` | 启用一个被禁用的扩展 |
| `/gsd extensions disable <id>` | 禁用一个扩展 |
| `/gsd extensions info <id>` | 查看扩展详情 |
| `/sf extensions list` | 列出所有扩展及其状态 |
| `/sf extensions enable <id>` | 启用一个被禁用的扩展 |
| `/sf extensions disable <id>` | 禁用一个扩展 |
| `/sf extensions info <id>` | 查看扩展详情 |
## cmux 集成
| 命令 | 说明 |
|------|------|
| `/gsd cmux status` | 显示 cmux 检测结果、prefs 和能力 |
| `/gsd cmux on` | 启用 cmux 集成 |
| `/gsd cmux off` | 禁用 cmux 集成 |
| `/gsd cmux notifications on/off` | 切换 cmux 桌面通知 |
| `/gsd cmux sidebar on/off` | 切换 cmux 侧边栏元数据 |
| `/gsd cmux splits on/off` | 切换 cmux subagent 可视化分屏 |
| `/sf cmux status` | 显示 cmux 检测结果、prefs 和能力 |
| `/sf cmux on` | 启用 cmux 集成 |
| `/sf cmux off` | 禁用 cmux 集成 |
| `/sf cmux notifications on/off` | 切换 cmux 桌面通知 |
| `/sf cmux sidebar on/off` | 切换 cmux 侧边栏元数据 |
| `/sf cmux splits on/off` | 切换 cmux subagent 可视化分屏 |
## GitHub Sync（v2.39）
| 命令 | 说明 |
|------|------|
| `/github-sync bootstrap` | 初始配置：根据当前 `.gsd/` 状态创建 GitHub Milestones、Issues 和 draft PRs |
| `/github-sync bootstrap` | 初始配置：根据当前 `.sf/` 状态创建 GitHub Milestones、Issues 和 draft PRs |
| `/github-sync status` | 显示同步映射数量（milestones、slices、tasks） |
在偏好设置里启用 `github.enabled: true`。要求已安装并认证 `gh` CLI。同步映射会保存在 `.gsd/.github-sync.json`。
在偏好设置里启用 `github.enabled: true`。要求已安装并认证 `gh` CLI。同步映射会保存在 `.sf/.github-sync.json`。
## Git 命令
@ -164,54 +164,54 @@
| 参数 | 说明 |
|------|------|
| `gsd` | 启动新的交互式会话 |
| `gsd --continue`（`-c`） | 恢复当前目录最近一次会话 |
| `gsd --model <id>` | 为当前会话覆盖默认模型 |
| `gsd --print "msg"`（`-p`） | 单次 prompt 模式（无 TUI） |
| `gsd --mode <text\|json\|rpc\|mcp>` | 非交互使用时的输出模式 |
| `gsd --list-models [search]` | 列出可用模型并退出 |
| `gsd --web [path]` | 启动基于浏览器的 Web 界面（可选项目路径） |
| `gsd --worktree`（`-w`）[name] | 在 git worktree 中启动会话（未指定时自动生成名称） |
| `gsd --no-session` | 禁用会话持久化 |
| `gsd --extension <path>` | 加载一个额外扩展（可重复） |
| `gsd --append-system-prompt <text>` | 向 system prompt 末尾追加文本 |
| `gsd --tools <list>` | 启用的工具列表，逗号分隔 |
| `gsd --version`（`-v`） | 输出版本并退出 |
| `gsd --help`（`-h`） | 输出帮助并退出 |
| `gsd sessions` | 交互式会话选择器：列出当前目录所有保存的会话并选择一个恢复 |
| `gsd --debug` | 启用结构化 JSONL 诊断日志，用于排查 dispatch 和 state 问题 |
| `gsd config` | 配置搜索和文档工具所需的全局 API keys（保存到 `~/.gsd/agent/auth.json`，对所有项目生效）。见 [Global API Keys](./configuration.md#global-api-keys-gsd-config)。 |
| `gsd update` | 更新到最新版本 |
| `gsd headless new-milestone` | 根据上下文文件创建新的 milestone（headless，无需 TUI） |
| `sf` | 启动新的交互式会话 |
| `sf --continue`（`-c`） | 恢复当前目录最近一次会话 |
| `sf --model <id>` | 为当前会话覆盖默认模型 |
| `sf --print "msg"`（`-p`） | 单次 prompt 模式（无 TUI） |
| `sf --mode <text\|json\|rpc\|mcp>` | 非交互使用时的输出模式 |
| `sf --list-models [search]` | 列出可用模型并退出 |
| `sf --web [path]` | 启动基于浏览器的 Web 界面（可选项目路径） |
| `sf --worktree`（`-w`）[name] | 在 git worktree 中启动会话（未指定时自动生成名称） |
| `sf --no-session` | 禁用会话持久化 |
| `sf --extension <path>` | 加载一个额外扩展（可重复） |
| `sf --append-system-prompt <text>` | 向 system prompt 末尾追加文本 |
| `sf --tools <list>` | 启用的工具列表，逗号分隔 |
| `sf --version`（`-v`） | 输出版本并退出 |
| `sf --help`（`-h`） | 输出帮助并退出 |
| `sf sessions` | 交互式会话选择器：列出当前目录所有保存的会话并选择一个恢复 |
| `sf --debug` | 启用结构化 JSONL 诊断日志，用于排查 dispatch 和 state 问题 |
| `sf config` | 配置搜索和文档工具所需的全局 API keys（保存到 `~/.sf/agent/auth.json`，对所有项目生效）。见 [Global API Keys](./configuration.md#global-api-keys-sf-config)。 |
| `sf update` | 更新到最新版本 |
| `sf headless new-milestone` | 根据上下文文件创建新的 milestone（headless，无需 TUI） |
## Headless 模式
`gsd headless` 可在无 TUI 的情况下运行 `/gsd` 命令，适合 CI、cron job 和脚本自动化。它会在 RPC 模式下启动一个子进程，自动回应交互式提示、检测完成状态，并用有意义的退出码退出。
`sf headless` 可在无 TUI 的情况下运行 `/sf` 命令，适合 CI、cron job 和脚本自动化。它会在 RPC 模式下启动一个子进程，自动回应交互式提示、检测完成状态，并用有意义的退出码退出。
```bash
# 运行自动模式（默认）
gsd headless
sf headless
# 运行一个单元
gsd headless next
sf headless next
# 即时 JSON 快照，无需 LLM，约 50ms
gsd headless query
sf headless query
# 用于 CI 的超时参数
gsd headless --timeout 600000 auto
sf headless --timeout 600000 auto
# 强制指定一个 phase
gsd headless dispatch plan
sf headless dispatch plan
# 根据上下文文件创建新 milestone，并启动自动模式
gsd headless new-milestone --context brief.md --auto
sf headless new-milestone --context brief.md --auto
# 用内联文本创建 milestone
gsd headless new-milestone --context-text "Build a REST API with auth"
sf headless new-milestone --context-text "Build a REST API with auth"
# 从 stdin 管道输入上下文
echo "Build a CLI tool" | gsd headless new-milestone --context -
echo "Build a CLI tool" | sf headless new-milestone --context -
```
| 参数 | 说明 |
@ -226,20 +226,20 @@ echo "Build a CLI tool" | gsd headless new-milestone --context -
**退出码：** `0` 表示完成，`1` 表示错误或超时，`2` 表示被阻塞。
任何 `/gsd` 子命令都可以作为位置参数使用，例如：`gsd headless status`、`gsd headless doctor`、`gsd headless dispatch execute` 等。
任何 `/sf` 子命令都可以作为位置参数使用，例如：`sf headless status`、`sf headless doctor`、`sf headless dispatch execute` 等。
### `gsd headless query`
### `sf headless query`
它会返回单个 JSON 对象，包含完整项目快照，无需 LLM 会话，也无需 RPC 子进程，响应几乎即时（约 50ms）。这是 orchestration 工具和脚本检查 SF 状态的推荐方式。
```bash
gsd headless query | jq '.state.phase'
sf headless query | jq '.state.phase'
# "executing"
gsd headless query | jq '.next'
sf headless query | jq '.next'
# {"action":"dispatch","unitType":"execute-task","unitId":"M001/S01/T03"}
gsd headless query | jq '.cost.total'
sf headless query | jq '.cost.total'
# 4.25
```
@ -271,21 +271,21 @@ gsd headless query | jq '.cost.total'
<a id="mcp-server-mode"></a>
## MCP Server 模式
`gsd --mode mcp` 会通过 stdin/stdout 将 SF 作为一个 [Model Context Protocol](https://modelcontextprotocol.io) server 运行。这会把所有 SF 工具（read、write、edit、bash 等）暴露给外部 AI 客户端，例如 Claude Desktop、VS Code Copilot，以及任何兼容 MCP 的宿主。
`sf --mode mcp` 会通过 stdin/stdout 将 SF 作为一个 [Model Context Protocol](https://modelcontextprotocol.io) server 运行。这会把所有 SF 工具（read、write、edit、bash 等）暴露给外部 AI 客户端，例如 Claude Desktop、VS Code Copilot，以及任何兼容 MCP 的宿主。
```bash
# 以 MCP server 模式启动 SF
gsd --mode mcp
sf --mode mcp
```
服务会注册 agent 会话中的全部工具，并把 MCP 的 `tools/list` 与 `tools/call` 请求映射到 SF 的工具定义上。连接会一直保持，直到底层 transport 关闭。
## 会话内更新
`/gsd update` 会检查 npm 上是否有更新版本，并在不离开当前会话的情况下完成安装。
`/sf update` 会检查 npm 上是否有更新版本，并在不离开当前会话的情况下完成安装。
```bash
/gsd update
/sf update
# Current version: v2.36.0
# Checking npm registry...
# Updated to v2.37.0. Restart SF to use the new version.
@ -295,14 +295,14 @@ gsd --mode mcp
## 导出
`/gsd export` 用于导出 milestone 工作报告。
`/sf export` 用于导出 milestone 工作报告。
```bash
# 为当前 active milestone 生成 HTML 报告
/gsd export --html
/sf export --html
# 一次性为所有 milestones 生成回顾报告
/gsd export --html --all
/sf export --html --all
```
报告会保存到 `.gsd/reports/`，并生成一个可浏览的 `index.html`，链接到所有已生成的快照。
报告会保存到 `.sf/reports/`，并生成一个可浏览的 `index.html`，链接到所有已生成的快照。

84
docs/zh-CN/user-docs/configuration.md
View file

@ -1,20 +1,20 @@
# 配置
SF 偏好设置保存在 `~/.gsd/PREFERENCES.md`（全局）或 `.gsd/PREFERENCES.md`（项目级）中。可以通过 `/gsd prefs` 进行交互式管理。
SF 偏好设置保存在 `~/.sf/PREFERENCES.md`（全局）或 `.sf/PREFERENCES.md`（项目级）中。可以通过 `/sf prefs` 进行交互式管理。
## `/gsd prefs` 命令
## `/sf prefs` 命令
| 命令 | 说明 |
|------|------|
| `/gsd prefs` | 打开全局偏好设置向导（默认） |
| `/gsd prefs global` | 全局偏好设置交互向导（`~/.gsd/PREFERENCES.md`） |
| `/gsd prefs project` | 项目偏好设置交互向导（`.gsd/PREFERENCES.md`） |
| `/gsd prefs status` | 显示当前偏好文件、合并后的值以及 skill 解析状态 |
| `/gsd prefs wizard` | `/gsd prefs global` 的别名 |
| `/gsd prefs setup` | `/gsd prefs wizard` 的别名；若偏好文件不存在会自动创建 |
| `/gsd prefs import-claude` | 将 Claude marketplace plugins 和 skills 以命名空间化的 SF 组件形式导入 |
| `/gsd prefs import-claude global` | 导入到全局作用域 |
| `/gsd prefs import-claude project` | 导入到项目作用域 |
| `/sf prefs` | 打开全局偏好设置向导（默认） |
| `/sf prefs global` | 全局偏好设置交互向导（`~/.sf/PREFERENCES.md`） |
| `/sf prefs project` | 项目偏好设置交互向导（`.sf/PREFERENCES.md`） |
| `/sf prefs status` | 显示当前偏好文件、合并后的值以及 skill 解析状态 |
| `/sf prefs wizard` | `/sf prefs global` 的别名 |
| `/sf prefs setup` | `/sf prefs wizard` 的别名；若偏好文件不存在会自动创建 |
| `/sf prefs import-claude` | 将 Claude marketplace plugins 和 skills 以命名空间化的 SF 组件形式导入 |
| `/sf prefs import-claude global` | 导入到全局作用域 |
| `/sf prefs import-claude project` | 导入到项目作用域 |
## 偏好文件格式
@ -42,8 +42,8 @@ token_profile: balanced
| 作用域 | 路径 | 适用范围 |
|--------|------|----------|
| 全局 | `~/.gsd/PREFERENCES.md` | 所有项目 |
| 项目 | `.gsd/PREFERENCES.md` | 仅当前项目 |
| 全局 | `~/.sf/PREFERENCES.md` | 所有项目 |
| 项目 | `.sf/PREFERENCES.md` | 仅当前项目 |
**合并规则：**
@ -51,13 +51,13 @@ token_profile: balanced
- **数组字段**（`always_use_skills` 等）：拼接，顺序为全局在前、项目在后
- **对象字段**（`models`、`git`、`auto_supervisor`）：浅合并，项目级按 key 覆盖
<a id="global-api-keys-gsd-config"></a>
## 全局 API Keys（`/gsd config`）
<a id="global-api-keys-sf-config"></a>
## 全局 API Keys（`/sf config`）
工具 API keys 会全局保存在 `~/.gsd/agent/auth.json` 中，并自动应用到所有项目。只需用 `/gsd config` 配置一次，无需在每个项目里维护 `.env`。
工具 API keys 会全局保存在 `~/.sf/agent/auth.json` 中，并自动应用到所有项目。只需用 `/sf config` 配置一次，无需在每个项目里维护 `.env`。
```bash
/gsd config
/sf config
```
这会打开一个交互式向导，显示哪些 key 已配置、哪些仍缺失。你可以选择一个工具并输入相应的 key。
@ -72,7 +72,7 @@ token_profile: balanced
### 工作方式
1. `/gsd config` 会把 keys 保存到 `~/.gsd/agent/auth.json`
1. `/sf config` 会把 keys 保存到 `~/.sf/agent/auth.json`
2. 每次会话启动时，`loadToolApiKeys()` 都会读取该文件并设置环境变量
3. 这些 keys 对所有项目生效，无需单独配置
4. 环境变量（例如 `export BRAVE_API_KEY=...`）优先级高于保存下来的 keys
@ -87,12 +87,12 @@ SF 可以连接配置在项目文件中的外部 MCP servers。这适合接入
SF 会从以下项目本地路径读取 MCP client 配置：
- `.mcp.json`
- `.gsd/mcp.json`
- `.sf/mcp.json`
如果两个文件都存在，会按 server 名称做合并，先找到的定义优先。通常建议：
- 把你愿意提交到仓库的共享 MCP 配置放在 `.mcp.json`
- 把仅本机使用、不希望共享的 MCP 配置放在 `.gsd/mcp.json`
- 把仅本机使用、不希望共享的 MCP 配置放在 `.sf/mcp.json`
### 支持的 transport
@ -150,15 +150,15 @@ mcp_call(server="my-server", tool="<tool_name>", args={...})
- 尽量为本地可执行文件和脚本使用绝对路径
- 对于 `stdio` servers，优先在 MCP 配置里显式设置需要的环境变量，而不是依赖交互式 shell profile
- SF 和 `gsd-mcp-server` 都会自动加载保存在 `~/.gsd/agent/auth.json` 中的 model / tool keys，因此 MCP 配置可以安全地通过 `${ENV_VAR}` 占位符引用这些值，而不必提交原始凭据
- SF 和 `sf-mcp-server` 都会自动加载保存在 `~/.sf/agent/auth.json` 中的 model / tool keys，因此 MCP 配置可以安全地通过 `${ENV_VAR}` 占位符引用这些值，而不必提交原始凭据
- 如果某个 server 是团队共享且适合提交到仓库，通常更适合放在 `.mcp.json`
- 如果某个 server 依赖本机路径、个人服务或本地 secrets，更适合放在 `.gsd/mcp.json`
- 如果某个 server 依赖本机路径、个人服务或本地 secrets，更适合放在 `.sf/mcp.json`
## 环境变量
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `SF_HOME` | `~/.gsd` | 全局 SF 目录。除非单独覆盖，否则其它路径都从这里派生。影响偏好、skills、sessions 以及项目状态。（v2.39） |
| `SF_HOME` | `~/.sf` | 全局 SF 目录。除非单独覆盖，否则其它路径都从这里派生。影响偏好、skills、sessions 以及项目状态。（v2.39） |
| `SF_PROJECT_ID` | （自动哈希） | 覆盖自动生成的项目身份哈希。这样项目状态会写入 `$SF_HOME/projects/<SF_PROJECT_ID>/`，而不是计算出的哈希目录。适用于 CI/CD 或多个克隆共享状态。（v2.39） |
| `SF_STATE_DIR` | `$SF_HOME` | 项目状态根目录。控制 `projects/<repo-hash>/` 的创建位置。对项目状态的优先级高于 `SF_HOME`。 |
| `SF_CODING_AGENT_DIR` | `$SF_HOME/agent` | agent 目录，包含托管资源、扩展和 auth。对 agent 相关路径的优先级高于 `SF_HOME`。 |
@ -193,13 +193,13 @@ models:
### 自定义 Model 定义（`models.json`）
你可以在 `~/.gsd/agent/models.json` 里定义自定义 models 和 providers。这允许你添加默认注册表里没有的 models，适合自托管 endpoints（Ollama、vLLM、LM Studio）、微调模型、代理，或者刚发布的新 provider。
你可以在 `~/.sf/agent/models.json` 里定义自定义 models 和 providers。这允许你添加默认注册表里没有的 models，适合自托管 endpoints（Ollama、vLLM、LM Studio）、微调模型、代理，或者刚发布的新 provider。
SF 读取 `models.json` 的顺序如下：
1. `~/.gsd/agent/models.json`：主位置（SF）
1. `~/.sf/agent/models.json`：主位置（SF）
2. `~/.pi/agent/models.json`：回退位置（Pi）
3. 如果两者都不存在，则创建 `~/.gsd/agent/models.json`
3. 如果两者都不存在，则创建 `~/.sf/agent/models.json`
**本地 models（Ollama）的快速示例：**
@ -243,7 +243,7 @@ models:
| 扩展 | Provider | Models | 安装命令 |
|------|----------|--------|----------|
| [`pi-dashscope`](https://www.npmjs.com/package/pi-dashscope) | Alibaba DashScope（ModelStudio） | Qwen3、GLM-5、MiniMax M2.5、Kimi K2.5 | `gsd install npm:pi-dashscope` |
| [`pi-dashscope`](https://www.npmjs.com/package/pi-dashscope) | Alibaba DashScope（ModelStudio） | Qwen3、GLM-5、MiniMax M2.5、Kimi K2.5 | `sf install npm:pi-dashscope` |
对于 DashScope models，更推荐使用社区扩展而不是内置的 `alibaba-coding-plan` provider，因为前者会走正确的 OpenAI-compatible endpoint，并包含适配 thinking mode 的 per-model compatibility flags。
@ -372,7 +372,7 @@ verification_max_retries: 2 # 最大重试次数（默认：2）
**允许特定内部主机：**
如果你确实需要 agent 访问内网 URL（例如自托管文档、VPN 后的内部 API），可以在全局设置 `~/.gsd/agent/settings.json` 中添加 `fetchAllowedUrls`：
如果你确实需要 agent 访问内网 URL（例如自托管文档、VPN 后的内部 API），可以在全局设置 `~/.sf/agent/settings.json` 中添加 `fetchAllowedUrls`：
```json
{
@ -398,7 +398,7 @@ export SF_FETCH_ALLOWED_URLS="internal-docs.company.com,192.168.1.50"
auto_report: true # 默认：true
```
报告会以自包含 HTML 文件的形式写入 `.gsd/reports/`，所有 CSS / JS 都内嵌。
报告会以自包含 HTML 文件的形式写入 `.sf/reports/`，所有 CSS / JS 都内嵌。
### `unique_milestone_ids`
@ -424,9 +424,9 @@ git:
main_branch: main # 主分支名称
merge_strategy: squash # worktree 分支合并方式："squash" 或 "merge"
isolation: worktree # git isolation："worktree"、"branch" 或 "none"
commit_docs: true # 是否把 .gsd/ 产物提交到 git（设为 false 时仅保留本地）
commit_docs: true # 是否把 .sf/ 产物提交到 git（设为 false 时仅保留本地）
manage_gitignore: true # 设为 false 时，SF 不再修改 .gitignore
worktree_post_create: .gsd/hooks/post-worktree-create # worktree 创建后执行的脚本
worktree_post_create: .sf/hooks/post-worktree-create # worktree 创建后执行的脚本
auto_pr: false # milestone 完成时自动创建 PR（要求 push_branches）
pr_target_branch: develop # 自动创建 PR 的目标分支（默认：main branch）
```
@ -442,7 +442,7 @@ git:
| `main_branch` | string | `"main"` | 主分支名称 |
| `merge_strategy` | string | `"squash"` | worktree 分支合并方式：`"squash"`（合并为单个提交）或 `"merge"`（保留单独提交） |
| `isolation` | string | `"worktree"` | 自动模式隔离方式：`"worktree"`（独立目录）、`"branch"`（直接在项目根目录工作，适合子模块多的仓库）、`"none"`（无隔离，直接提交到当前分支） |
| `commit_docs` | boolean | `true` | 是否把 `.gsd/` planning 产物提交到 git。设为 `false` 则仅保留本地 |
| `commit_docs` | boolean | `true` | 是否把 `.sf/` planning 产物提交到 git。设为 `false` 则仅保留本地 |
| `manage_gitignore` | boolean | `true` | 设为 `false` 后，SF 将完全不修改 `.gitignore`，不会添加基础规则，也不会做自愈 |
| `worktree_post_create` | string | （无） | worktree 创建后执行的脚本。环境变量中会传入 `SOURCE_DIR` 和 `WORKTREE_DIR` |
| `auto_pr` | boolean | `false` | milestone 完成时自动创建 pull request。要求 `auto_push: true` 且已安装认证 `gh` CLI |
@ -454,7 +454,7 @@ git:
```yaml
git:
worktree_post_create: .gsd/hooks/post-worktree-create
worktree_post_create: .sf/hooks/post-worktree-create
```
脚本会收到两个环境变量：
@ -462,7 +462,7 @@ git:
- `SOURCE_DIR`：原始项目根目录
- `WORKTREE_DIR`：新创建的 worktree 路径
示例 hook（`.gsd/hooks/post-worktree-create`）：
示例 hook（`.sf/hooks/post-worktree-create`）：
```bash
#!/bin/bash
@ -508,7 +508,7 @@ GitHub 同步配置。启用后，SF 会自动把 milestones、slices 和 tasks
github:
enabled: true
repo: "owner/repo" # 省略时从 git remote 自动检测
labels: [gsd, auto-generated] # 应用到创建出的 issues / PRs 的标签
labels: [sf, auto-generated] # 应用到创建出的 issues / PRs 的标签
project: "Project ID" # 可选的 GitHub Project board
```
@ -522,7 +522,7 @@ github:
**要求：**
- 已安装并认证 `gh` CLI（`gh auth login`）
- 同步映射会保存在 `.gsd/.github-sync.json`
- 同步映射会保存在 `.sf/.github-sync.json`
- 具备速率限制感知：当 GitHub API rate limit 偏低时会跳过同步
**命令：**
@ -662,13 +662,13 @@ custom_instructions:
- "Prefer functional patterns over classes"
```
如果是项目特有知识（模式、坑点、经验），请优先放到 `.gsd/KNOWLEDGE.md` 中，因为它会自动注入每个 agent prompt。你也可以通过 `/gsd knowledge rule|pattern|lesson <description>` 添加。
如果是项目特有知识（模式、坑点、经验），请优先放到 `.sf/KNOWLEDGE.md` 中，因为它会自动注入每个 agent prompt。你也可以通过 `/sf knowledge rule|pattern|lesson <description>` 添加。
### `RUNTIME.md`：运行时上下文（v2.39）
你可以在 `.gsd/RUNTIME.md` 中声明项目级运行时上下文。这个文件会内联进 task execution prompt，让 agent 能准确知道运行环境，而不必靠猜测路径或 URL。
你可以在 `.sf/RUNTIME.md` 中声明项目级运行时上下文。这个文件会内联进 task execution prompt，让 agent 能准确知道运行环境，而不必靠猜测路径或 URL。
**位置：** `.gsd/RUNTIME.md`
**位置：** `.sf/RUNTIME.md`
**示例：**
@ -721,7 +721,7 @@ context_management:
### `service_tier`（v2.42）
OpenAI 支持模型的 service tier 偏好。可通过 `/gsd fast` 切换。
OpenAI 支持模型的 service tier 偏好。可通过 `/sf fast` 切换。
| 值 | 行为 |
|----|------|
@ -735,7 +735,7 @@ service_tier: priority
### `forensics_dedup`（v2.43）
可选启用：在 `/gsd forensics` 提交 issue 之前，先搜索现有 issues 和 PRs。会额外消耗一些 AI tokens。
可选启用：在 `/sf forensics` 提交 issue 之前，先搜索现有 issues 和 PRs。会额外消耗一些 AI tokens。
```yaml
forensics_dedup: true # 默认：false
@ -836,7 +836,7 @@ notifications:
auto_visualize: true
# Service tier
service_tier: priority # "priority" or "flex" (for /gsd fast)
service_tier: priority # "priority" or "flex" (for /sf fast)
# Diagnostics
forensics_dedup: true # deduplicate before filing forensics issues

8
docs/zh-CN/user-docs/cost-management.md
View file

@ -12,11 +12,11 @@ SF 会跟踪自动模式中每个派发工作单元的 Token 使用量和成本
- **工具调用数**：工具调用次数
- **消息数量**：assistant 与 user 消息数
数据保存在 `.gsd/metrics.json` 中，并且可跨会话持续存在。
数据保存在 `.sf/metrics.json` 中，并且可跨会话持续存在。
### 查看成本
**仪表板**：按 `Ctrl+Alt+G` 或执行 `/gsd status` 可查看实时成本拆分。
**仪表板**：按 `Ctrl+Alt+G` 或执行 `/sf status` 可查看实时成本拆分。
**可用聚合维度：**
@ -86,9 +86,9 @@ Projected remaining: $12.40 ($6.20/slice avg × 2 remaining)
## 建议
- 先用 `balanced` 配置，并设置一个较宽松的 `budget_ceiling` 来建立成本基线
- 完成几个 slices 后查看 `/gsd status`，确认每个 slice 的平均成本
- 完成几个 slices 后查看 `/sf status`，确认每个 slice 的平均成本
- 对于已知流程、重复性高的工作，切换到 `budget` 配置
- 只有在做架构决策时才建议使用 `quality`
- 可以通过按阶段选模型，只在 planning 使用 Opus，而在 execution 保持 Sonnet
- 开启 `dynamic_routing`，让简单 task 自动下沉到更便宜的模型，详见 [动态模型路由](./dynamic-model-routing.md)
- 使用 `/gsd visualize` 的 Metrics 标签页查看预算具体花在了哪里
- 使用 `/sf visualize` 的 Metrics 标签页查看预算具体花在了哪里

6
docs/zh-CN/user-docs/custom-models.md
View file

@ -1,6 +1,6 @@
# 自定义模型
通过 `~/.gsd/agent/models.json` 添加自定义 providers 和 models（Ollama、vLLM、LM Studio、代理等）。
通过 `~/.sf/agent/models.json` 添加自定义 providers 和 models（Ollama、vLLM、LM Studio、代理等）。
## 目录
@ -149,7 +149,7 @@ Shell 命令（`!command`）只能执行一组已知的凭据工具。只有以
**自定义允许列表：**
如果你使用的凭据工具不在默认列表中，可以在全局设置（`~/.gsd/agent/settings.json`）里覆盖：
如果你使用的凭据工具不在默认列表中，可以在全局设置（`~/.sf/agent/settings.json`）里覆盖：
```json
{
@ -165,7 +165,7 @@ Shell 命令（`!command`）只能执行一组已知的凭据工具。只有以
export SF_ALLOWED_COMMAND_PREFIXES="pass,op,sops,doppler"
```
> **注意：** 这是一个仅全局生效的设置。项目级 settings.json（`<project>/.gsd/settings.json`）不能覆盖命令 allowlist，以防克隆下来的仓库提升命令执行权限。
> **注意：** 这是一个仅全局生效的设置。项目级 settings.json（`<project>/.sf/settings.json`）不能覆盖命令 allowlist，以防克隆下来的仓库提升命令执行权限。
### 自定义 Headers

2
docs/zh-CN/user-docs/dynamic-model-routing.md
View file

@ -260,7 +260,7 @@ pi.on("before_model_select", async (event) => {
### 自适应学习
路由历史（`.gsd/routing-history.json`）会按 unit type 和 tier 记录成功 / 失败情况。如果某种模式下某个 tier 的失败率超过 20%，未来相似分类会自动上调一个 tier。用户反馈（`over` / `under` / `ok`）的权重是自动结果的 2 倍。
路由历史（`.sf/routing-history.json`）会按 unit type 和 tier 记录成功 / 失败情况。如果某种模式下某个 tier 的失败率超过 20%，未来相似分类会自动上调一个 tier。用户反馈（`over` / `under` / `ok`）的权重是自动结果的 2 倍。
## 与 Token Profile 的关系

80
docs/zh-CN/user-docs/getting-started.md
View file

@ -54,7 +54,7 @@ npm install -g sf-run
export ANTHROPIC_API_KEY="sk-ant-..."
# 选项 B：使用内置配置向导
gsd config
sf config
```
如果想永久保存这个 key，把 export 语句写入 `~/.zshrc`：
@ -70,24 +70,24 @@ source ~/.zshrc
```bash
cd ~/my-project # 进入任意项目目录
gsd # 启动一个会话
sf # 启动一个会话
```
**第 7 步：确认一切正常：**
```bash
gsd --version # 输出已安装版本
sf --version # 输出已安装版本
```
进入会话后，输入 `/model` 以确认你的 LLM 已成功连接。
> **Apple Silicon PATH 修复：** 如果安装后找不到 `gsd`，可能是 npm 的全局 bin 目录没有加入 PATH：
> **Apple Silicon PATH 修复：** 如果安装后找不到 `sf`，可能是 npm 的全局 bin 目录没有加入 PATH：
> ```bash
> echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
> source ~/.zshrc
> ```
> **oh-my-zsh 冲突：** oh-my-zsh 的 git 插件定义了 `alias gsd='git svn dcommit'`。可在 `~/.zshrc` 中加入 `unalias gsd 2>/dev/null`，或者改用 `gsd-cli`。
> **oh-my-zsh 冲突：** oh-my-zsh 的 git 插件定义了 `alias sf='git svn dcommit'`。可在 `~/.zshrc` 中加入 `unalias sf 2>/dev/null`，或者改用 `sf-cli`。
---
@ -126,7 +126,7 @@ npm install -g sf-run
$env:ANTHROPIC_API_KEY = "sk-ant-..."
# 选项 B：使用内置配置向导
gsd config
sf config
```
如果要永久保存该 key，可在系统设置的环境变量中添加，或者执行：
@ -141,13 +141,13 @@ gsd config
```powershell
cd C:\Users\you\my-project # 进入任意项目目录
gsd # 启动一个会话
sf # 启动一个会话
```
**第 7 步：确认一切正常：**
```powershell
gsd --version # 输出已安装版本
sf --version # 输出已安装版本
```
进入会话后，输入 `/model` 以确认你的 LLM 已成功连接。
@ -160,7 +160,7 @@ gsd --version # 输出已安装版本
> **Windows 提示：**
> - 建议使用 **Windows Terminal** 或 **PowerShell**，体验最佳。Command Prompt 也能用，但颜色支持较弱。
> - 如果 `gsd` 无法识别，先重启终端。Windows 需要新开终端才能读取更新后的 PATH。
> - 如果 `sf` 无法识别，先重启终端。Windows 需要新开终端才能读取更新后的 PATH。
> - **WSL2** 也可用，安装 WSL 后，在发行版内部按 Linux 说明继续。
---
@ -230,7 +230,7 @@ npm install -g sf-run
export ANTHROPIC_API_KEY="sk-ant-..."
# 选项 B：使用内置配置向导
gsd config
sf config
```
如果想永久保存这个 key，把 export 语句写到 `~/.bashrc`（或 `~/.zshrc`）中：
@ -246,13 +246,13 @@ source ~/.bashrc
```bash
cd ~/my-project # 进入任意项目目录
gsd # 启动一个会话
sf # 启动一个会话
```
**第 6 步：确认一切正常：**
```bash
gsd --version # 输出已安装版本
sf --version # 输出已安装版本
```
进入会话后，输入 `/model` 以确认你的 LLM 已成功连接。
@ -280,21 +280,21 @@ gsd --version # 输出已安装版本
```bash
git clone https://github.com/singularity-forge/sf-run.git
cd gsd-2/docker
cd sf-2/docker
```
**第 3 步：创建并进入沙箱：**
```bash
docker sandbox create --template . --name gsd-sandbox
docker sandbox exec -it gsd-sandbox bash
docker sandbox create --template . --name sf-sandbox
docker sandbox exec -it sf-sandbox bash
```
**第 4 步：设置 API key 并运行 SF：**
```bash
export ANTHROPIC_API_KEY="sk-ant-..."
gsd auto "implement the feature described in issue #42"
sf auto "implement the feature described in issue #42"
```
完整的配置、资源限制和 compose 文件请见 [Docker Sandbox 文档](../../../docker/README.md)。
@ -317,23 +317,23 @@ gsd auto "implement the feature described in issue #42"
## 两种工作方式
### 步骤模式 — `/gsd`
### 步骤模式 — `/sf`
在会话内输入 `/gsd`。SF 会一次执行一个工作单元，并在每一步之间暂停，通过向导展示刚完成了什么、下一步是什么。
在会话内输入 `/sf`。SF 会一次执行一个工作单元，并在每一步之间暂停，通过向导展示刚完成了什么、下一步是什么。
- **没有 `.gsd/` 目录**：启动讨论流程，先收集你的项目愿景
- **没有 `.sf/` 目录**：启动讨论流程，先收集你的项目愿景
- **已有 milestone，但没有 roadmap**：讨论或研究该 milestone
- **roadmap 已存在，仍有待完成的 slices**：规划下一个 slice 或执行一个 task
- **进行到一半的 task**：从上次停下的地方继续
步骤模式会让你始终留在回路中，在每一步之间查看和确认输出。
### 自动模式 — `/gsd auto`
### 自动模式 — `/sf auto`
输入 `/gsd auto` 后就可以离开。SF 会自主完成 research、planning、execution、verification、commit，并持续推进每个 slice，直到 milestone 完成。
输入 `/sf auto` 后就可以离开。SF 会自主完成 research、planning、execution、verification、commit，并持续推进每个 slice，直到 milestone 完成。
```
/gsd auto
/sf auto
```
完整细节请见 [自动模式](./auto-mode.md)。
@ -347,20 +347,20 @@ gsd auto "implement the feature described in issue #42"
**终端 1：让它构建**
```bash
gsd
/gsd auto
sf
/sf auto
```
**终端 2：在它工作时进行引导**
```bash
gsd
/gsd discuss # 讨论架构决策
/gsd status # 查看进度
/gsd queue # 排队下一个 milestone
sf
/sf discuss # 讨论架构决策
/sf status # 查看进度
/sf queue # 排队下一个 milestone
```
两个终端都会读写同一套 `.gsd/` 文件。你在终端 2 里做出的决策，会在下一个阶段边界被自动拾取。
两个终端都会读写同一套 `.sf/` 文件。你在终端 2 里做出的决策，会在下一个阶段边界被自动拾取。
---
@ -374,10 +374,10 @@ Milestone → 一个可交付版本（4-10 个 slice）
铁律是：**一个 task 必须能装进一个上下文窗口。** 装不下，就说明它应该拆成两个 task。
所有状态都保存在 `.gsd/` 中：
所有状态都保存在 `.sf/` 中：
```
.gsd/
.sf/
PROJECT.md — 项目当前是什么
REQUIREMENTS.md — 需求契约
DECISIONS.md — 追加式架构决策记录
@ -398,7 +398,7 @@ Milestone → 一个可交付版本（4-10 个 slice）
SF 也提供 VS Code 扩展。你可以从扩展市场安装（publisher: FluxLabs），或者在 VS Code 扩展面板中直接搜索 “SF”：
- **`@gsd` 聊天参与者**：在 VS Code Chat 中直接与 agent 对话
- **`@sf` 聊天参与者**：在 VS Code Chat 中直接与 agent 对话
- **侧边栏仪表板**：显示连接状态、模型信息、Token 使用量
- **完整命令面板**：启动 / 停止 agent、切换模型、导出会话
@ -411,7 +411,7 @@ CLI（`sf-run`）需要先安装好，扩展会通过 RPC 与其连接。
SF 也提供一个基于浏览器的可视化项目管理界面：
```bash
gsd --web
sf --web
```
详见 [Web 界面](./web-interface.md)。
@ -421,7 +421,7 @@ gsd --web
## 恢复会话
```bash
gsd --continue # 或 gsd -c
sf --continue # 或 sf -c
```
会恢复当前目录最近一次会话。
@ -429,7 +429,7 @@ gsd --continue # 或 gsd -c
浏览所有保存过的会话：
```bash
gsd sessions
sf sessions
```
---
@ -445,7 +445,7 @@ npm update -g sf-run
或者在会话中执行：
```
/gsd update
/sf update
```
---
@ -454,11 +454,11 @@ npm update -g sf-run
| 问题 | 解决方式 |
|------|----------|
| `command not found: gsd` | 把 npm 全局 bin 目录加入 PATH（见上面的系统说明） |
| `gsd` 实际执行了 `git svn dcommit` | oh-my-zsh 冲突，执行 `unalias gsd` 或改用 `gsd-cli` |
| `command not found: sf` | 把 npm 全局 bin 目录加入 PATH（见上面的系统说明） |
| `sf` 实际执行了 `git svn dcommit` | oh-my-zsh 冲突，执行 `unalias sf` 或改用 `sf-cli` |
| `npm install -g sf-run` 权限错误 | 修复 npm prefix（见 Linux 说明）或改用 nvm |
| 无法连接到 LLM | 用 `gsd config` 检查 API key，并确认网络可用 |
| `gsd` 启动时卡住 | 检查 Node.js 版本：`node --version`（需要 22+） |
| 无法连接到 LLM | 用 `sf config` 检查 API key，并确认网络可用 |
| `sf` 启动时卡住 | 检查 Node.js 版本：`node --version`（需要 22+） |
更多问题见 [故障排查](./troubleshooting.md)。

14
docs/zh-CN/user-docs/git-strategy.md
View file

@ -8,13 +8,13 @@ SF 支持三种隔离模式，通过 `git.isolation` 偏好设置：
| 模式 | 工作目录 | 分支 | 适用场景 |
|------|----------|------|----------|
| `worktree`（默认） | `.gsd/worktrees/<MID>/` | `milestone/<MID>` | 大多数项目，milestones 之间文件完全隔离 |
| `worktree`（默认） | `.sf/worktrees/<MID>/` | `milestone/<MID>` | 大多数项目，milestones 之间文件完全隔离 |
| `branch` | 项目根目录 | `milestone/<MID>` | 子模块较多、worktree 表现不佳的仓库 |
| `none` | 项目根目录 | 当前分支（不建 milestone 分支） | 热重载工作流中，文件隔离会破坏开发工具的场景 |
### `worktree` 模式（默认）
每个 milestone 都会在 `.gsd/worktrees/<MID>/` 下拥有自己的 git worktree，对应一个 `milestone/<MID>` 分支。所有执行都发生在该 worktree 中。完成后，worktree 会被 squash merge 回主分支，形成一个干净的提交，然后清理对应 worktree 和分支。
每个 milestone 都会在 `.sf/worktrees/<MID>/` 下拥有自己的 git worktree，对应一个 `milestone/<MID>` 分支。所有执行都发生在该 worktree 中。完成后，worktree 会被 squash merge 回主分支，形成一个干净的提交，然后清理对应 worktree 和分支。
这提供了完整的文件隔离，某个 milestone 的变更不会干扰你的主工作副本。
@ -95,8 +95,8 @@ SF-Task: M001/S01/T02
自动模式会自动创建并管理 worktrees：
1. milestone 启动时，在 `.gsd/worktrees/<MID>/` 创建 worktree，并切到 `milestone/<MID>` 分支
2. 将 `.gsd/milestones/` 下的规划产物复制到该 worktree
1. milestone 启动时，在 `.sf/worktrees/<MID>/` 创建 worktree，并切到 `milestone/<MID>` 分支
2. 将 `.sf/milestones/` 下的规划产物复制到该 worktree
3. 所有执行都发生在 worktree 内部
4. milestone 完成后，把该 worktree squash merge 回集成分支
5. 删除 worktree 和对应分支
@ -148,7 +148,7 @@ git:
pre_merge_check: false # 合并前校验
commit_type: feat # 覆盖提交类型前缀
main_branch: main # 主分支名称
commit_docs: true # 将 .gsd/ 提交到 git
commit_docs: true # 将 .sf/ 提交到 git
isolation: worktree # "worktree"、"branch" 或 "none"
auto_pr: false # milestone 完成时自动创建 PR
pr_target_branch: develop # PR 目标分支（默认 main）
@ -169,7 +169,7 @@ git:
### `commit_docs: false`
当设置为 `false` 时，SF 会把 `.gsd/` 添加到 `.gitignore`，所有规划产物只保留在本地。适合只有部分成员使用 SF 的团队，或者公司要求仓库保持干净的场景。
当设置为 `false` 时，SF 会把 `.sf/` 添加到 `.gitignore`，所有规划产物只保留在本地。适合只有部分成员使用 SF 的团队，或者公司要求仓库保持干净的场景。
## 自愈能力
@ -179,7 +179,7 @@ SF 内置了对常见 git 问题的自动恢复：
- **过期锁文件**：移除崩溃进程残留的 `index.lock`
- **孤儿 worktree**：检测并提供清理废弃 worktree 的选项（仅 worktree 模式）
可通过 `/gsd doctor` 手动检查 git 健康状态。
可通过 `/sf doctor` 手动检查 git 健康状态。
## 原生 Git 操作

10
docs/zh-CN/user-docs/migration.md
View file

@ -1,15 +1,15 @@
# 从 v1 迁移
如果你有仍在使用原始 Singularity Forge（v1）`.planning` 目录结构的项目，可以把它们迁移到 SF 的 `.gsd` 格式。
如果你有仍在使用原始 Singularity Forge（v1）`.planning` 目录结构的项目，可以把它们迁移到 SF 的 `.sf` 格式。
## 运行迁移
```bash
# 在项目目录内执行
/gsd migrate
/sf migrate
# 或者显式指定路径
/gsd migrate ~/projects/my-old-project
/sf migrate ~/projects/my-old-project
```
## 会迁移什么
@ -42,7 +42,7 @@
迁移完成后，用下面的命令检查输出结果：
```bash
/gsd doctor
/sf doctor
```
它会检查 `.gsd/` 的完整性，并标出任何结构性问题。
它会检查 `.sf/` 的完整性，并标出任何结构性问题。

2
docs/zh-CN/user-docs/node-lts-macos.md
View file

@ -71,5 +71,5 @@ brew unpin node@24
```bash
node --version # v24.x.x
npm install -g sf-run
gsd --version
sf --version
```

82
docs/zh-CN/user-docs/parallel-orchestration.md
View file

@ -19,7 +19,7 @@ parallel:
2. 启动并行执行：
```
/gsd parallel start
/sf parallel start
```
SF 会扫描所有 milestones，检查依赖与文件重叠，给出一份可并行性报告，并为符合条件的 milestones 启动 workers。
@ -27,13 +27,13 @@ SF 会扫描所有 milestones，检查依赖与文件重叠，给出一份可并
3. 监控进度：
```
/gsd parallel status
/sf parallel status
```
4. 完成后停止：
```
/gsd parallel stop
/sf parallel stop
```
## 工作原理
@ -58,7 +58,7 @@ SF 会扫描所有 milestones，检查依赖与文件重叠，给出一份可并
│ └──────────┘ └──────────┘ └──────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ .gsd/worktrees/ .gsd/worktrees/ .gsd/worktrees/ │
│ .sf/worktrees/ .sf/worktrees/ .sf/worktrees/ │
│ M001/ M003/ M005/ │
│ (milestone/ (milestone/ (milestone/ │
│ M001 branch) M003 branch) M005 branch) │
@ -67,7 +67,7 @@ SF 会扫描所有 milestones，检查依赖与文件重叠，给出一份可并
### Worker 隔离
每个 worker 都是一个完全隔离的独立 `gsd` 进程：
每个 worker 都是一个完全隔离的独立 `sf` 进程：
| 资源 | 隔离方式 |
|------|----------|
@ -75,15 +75,15 @@ SF 会扫描所有 milestones，检查依赖与文件重叠，给出一份可并
| **Git 分支** | `milestone/<MID>`：每个 milestone 一条分支 |
| **状态推导** | 通过 `SF_MILESTONE_LOCK` 环境变量，让 `deriveState()` 只看到被分配的 milestone |
| **上下文窗口** | 独立进程：每个 worker 都有自己的 agent sessions |
| **指标** | 每个 worktree 都有自己的 `.gsd/metrics.json` |
| **崩溃恢复** | 每个 worktree 都有自己的 `.gsd/auto.lock` |
| **指标** | 每个 worktree 都有自己的 `.sf/metrics.json` |
| **崩溃恢复** | 每个 worktree 都有自己的 `.sf/auto.lock` |
### 协调方式
Workers 和 coordinator 通过基于文件的 IPC 通信：
- **会话状态文件**（`.gsd/parallel/<MID>.status.json`）：worker 写入 heartbeat，coordinator 读取
- **信号文件**（`.gsd/parallel/<MID>.signal.json`）：coordinator 写信号，worker 消费
- **会话状态文件**（`.sf/parallel/<MID>.status.json`）：worker 写入 heartbeat，coordinator 读取
- **信号文件**（`.sf/parallel/<MID>.signal.json`）：coordinator 写信号，worker 消费
- **原子写入**：使用写临时文件再 rename 的方式，避免读到半成品
## 可并行性分析
@ -126,7 +126,7 @@ Workers 和 coordinator 通过基于文件的 IPC 通信：
## 配置
把下面内容加到 `~/.gsd/PREFERENCES.md` 或 `.gsd/PREFERENCES.md`：
把下面内容加到 `~/.sf/PREFERENCES.md` 或 `.sf/PREFERENCES.md`：
```yaml
---
@ -143,26 +143,26 @@ parallel:
| Key | 类型 | 默认值 | 说明 |
|-----|------|--------|------|
| `enabled` | boolean | `false` | 总开关。只有设为 `true`，`/gsd parallel` 命令才可用。 |
| `enabled` | boolean | `false` | 总开关。只有设为 `true`，`/sf parallel` 命令才可用。 |
| `max_workers` | number（1-4） | `2` | 最大并发 worker 进程数。值越高，内存与 API 预算消耗也越高。 |
| `budget_ceiling` | number | 无 | 所有 workers 的聚合美元预算上限。达到后不会再派发新单元。 |
| `merge_strategy` | `"per-slice"` 或 `"per-milestone"` | `"per-milestone"` | worktree 变更何时回合并到主分支。Per-milestone 会等整个 milestone 完成后再合并。 |
| `auto_merge` | `"auto"`、`"confirm"`、`"manual"` | `"confirm"` | merge-back 策略。`confirm` 会在合并前询问；`manual` 要求显式执行 `/gsd parallel merge`。 |
| `auto_merge` | `"auto"`、`"confirm"`、`"manual"` | `"confirm"` | merge-back 策略。`confirm` 会在合并前询问；`manual` 要求显式执行 `/sf parallel merge`。 |
## 命令
| 命令 | 说明 |
|------|------|
| `/gsd parallel start` | 分析可并行性、确认并启动 workers |
| `/gsd parallel status` | 显示所有 workers 的状态、已完成单元和成本 |
| `/gsd parallel stop` | 停止所有 workers（发送 SIGTERM） |
| `/gsd parallel stop M002` | 停止某个指定 milestone 的 worker |
| `/gsd parallel pause` | 暂停所有 workers（完成当前单元后等待） |
| `/gsd parallel pause M002` | 暂停某个指定 worker |
| `/gsd parallel resume` | 恢复所有已暂停 workers |
| `/gsd parallel resume M002` | 恢复某个指定 worker |
| `/gsd parallel merge` | 把所有已完成 milestones 合并回 main |
| `/gsd parallel merge M002` | 只把某个指定 milestone 合并回 main |
| `/sf parallel start` | 分析可并行性、确认并启动 workers |
| `/sf parallel status` | 显示所有 workers 的状态、已完成单元和成本 |
| `/sf parallel stop` | 停止所有 workers（发送 SIGTERM） |
| `/sf parallel stop M002` | 停止某个指定 milestone 的 worker |
| `/sf parallel pause` | 暂停所有 workers（完成当前单元后等待） |
| `/sf parallel pause M002` | 暂停某个指定 worker |
| `/sf parallel resume` | 恢复所有已暂停 workers |
| `/sf parallel resume M002` | 恢复某个指定 worker |
| `/sf parallel merge` | 把所有已完成 milestones 合并回 main |
| `/sf parallel merge M002` | 只把某个指定 milestone 合并回 main |
## 信号生命周期
@ -200,13 +200,13 @@ Workers 会在单元之间检查信号（位于 `handleAgentEnd`）。在 stop
### 冲突处理
1. `.gsd/` 状态文件（如 `STATE.md`、`metrics.json`）会**自动解决**，默认接受 milestone 分支版本
2. 代码冲突则会**停止并报告**。合并会暂停，并显示哪些文件冲突。你需要手动解决后，再执行 `/gsd parallel merge <MID>` 重试
1. `.sf/` 状态文件（如 `STATE.md`、`metrics.json`）会**自动解决**，默认接受 milestone 分支版本
2. 代码冲突则会**停止并报告**。合并会暂停，并显示哪些文件冲突。你需要手动解决后，再执行 `/sf parallel merge <MID>` 重试
### 示例
```
/gsd parallel merge
/sf parallel merge
# Merge Results
@ -214,7 +214,7 @@ Workers 会在单元之间检查信号（位于 `handleAgentEnd`）。在 stop
- **M003** — CONFLICT (2 file(s)):
- `src/types.ts`
- `src/middleware.ts`
Resolve conflicts manually and run `/gsd parallel merge M003` to retry.
Resolve conflicts manually and run `/sf parallel merge M003` to retry.
```
## 预算管理
@ -229,11 +229,11 @@ Workers 会在单元之间检查信号（位于 `handleAgentEnd`）。在 stop
### Doctor 集成
`/gsd doctor` 能检测并行会话相关问题：
`/sf doctor` 能检测并行会话相关问题：
- **过期的并行会话**：worker 进程已经死亡，但没有清理干净。Doctor 会检查 `.gsd/parallel/*.status.json` 中记录的 PID 和 heartbeat，发现失效后自动清理。
- **过期的并行会话**：worker 进程已经死亡，但没有清理干净。Doctor 会检查 `.sf/parallel/*.status.json` 中记录的 PID 和 heartbeat，发现失效后自动清理。
可以执行 `/gsd doctor --fix` 自动清理。
可以执行 `/sf doctor --fix` 自动清理。
### 过期检测
@ -256,12 +256,12 @@ Coordinator 会在 `refreshWorkerStatuses()` 中执行 stale detection，并自
| **预算上限** | 跨所有 workers 执行聚合成本限制 |
| **信号式关闭** | 通过文件信号 + SIGTERM 优雅停止 |
| **Doctor 集成** | 检测并清理孤儿会话 |
| **冲突感知 merge** | 遇到代码冲突时停止；`.gsd/` 状态冲突自动解决 |
| **冲突感知 merge** | 遇到代码冲突时停止；`.sf/` 状态冲突自动解决 |
## 文件布局
```
.gsd/
.sf/
├── parallel/ # Coordinator ↔ worker IPC
│ ├── M002.status.json # Worker heartbeat + progress
│ ├── M002.signal.json # Coordinator → worker signals
@ -269,7 +269,7 @@ Coordinator 会在 `refreshWorkerStatuses()` 中执行 stale detection，并自
│ └── M003.signal.json
├── worktrees/ # Git worktrees（每个 milestone 一个）
│ ├── M002/ # M002 的隔离 checkout
│ │ ├── .gsd/ # M002 自己的状态文件
│ │ ├── .sf/ # M002 自己的状态文件
│ │ │ ├── auto.lock
│ │ │ ├── metrics.json
│ │ │ └── milestones/
@ -279,7 +279,7 @@ Coordinator 会在 `refreshWorkerStatuses()` 中执行 stale detection，并自
└── ...
```
`.gsd/parallel/` 和 `.gsd/worktrees/` 都会被 gitignore，因为它们只是运行时协调文件，永远不会提交。
`.sf/parallel/` 和 `.sf/worktrees/` 都会被 gitignore，因为它们只是运行时协调文件，永远不会提交。
## 故障排查
@ -289,22 +289,22 @@ Coordinator 会在 `refreshWorkerStatuses()` 中执行 stale detection，并自
### “No milestones are eligible for parallel execution”
说明所有 milestones 要么已完成，要么被依赖阻塞。可通过 `/gsd queue` 查看 milestone 状态和依赖链。
说明所有 milestones 要么已完成，要么被依赖阻塞。可通过 `/sf queue` 查看 milestone 状态和依赖链。
### Worker 崩溃后如何恢复
Workers 会自动把状态持久化到磁盘。如果某个 worker 进程死亡，coordinator 会通过 heartbeat 超时检测到死掉的 PID，并把该 worker 标记为 crashed。重启后，worker 会从磁盘状态继续：崩溃恢复、worktree 重入和 completed-unit 跟踪都会延续之前的状态。
1. 执行 `/gsd doctor --fix` 清理 stale sessions
2. 执行 `/gsd parallel status` 查看当前状态
3. 重新执行 `/gsd parallel start`，为剩余 milestones 启动新的 workers
1. 执行 `/sf doctor --fix` 清理 stale sessions
2. 执行 `/sf parallel status` 查看当前状态
3. 重新执行 `/sf parallel start`，为剩余 milestones 启动新的 workers
### 并行执行完成后发生 merge 冲突
1. 执行 `/gsd parallel merge` 查看哪些 milestones 存在冲突
2. 在 `.gsd/worktrees/<MID>/` 对应的 worktree 中手动解决冲突
3. 执行 `/gsd parallel merge <MID>` 重试
1. 执行 `/sf parallel merge` 查看哪些 milestones 存在冲突
2. 在 `.sf/worktrees/<MID>/` 对应的 worktree 中手动解决冲突
3. 执行 `/sf parallel merge <MID>` 重试
### Workers 看起来卡住了
先检查是否触达了预算上限：`/gsd parallel status` 会显示每个 worker 的成本。继续执行的话，提升 `parallel.budget_ceiling` 或直接移除它。
先检查是否触达了预算上限：`/sf parallel status` 会显示每个 worker 的成本。继续执行的话，提升 `parallel.budget_ceiling` 或直接移除它。

52
docs/zh-CN/user-docs/providers.md
View file

@ -1,6 +1,6 @@
# Provider 设置指南
这是一份覆盖 SF 所有受支持 LLM providers 的分步配置指南。如果你已经运行过 onboarding 向导（`gsd config`）并选择了 provider，很可能已经配置完成，可以在会话中用 `/model` 检查。
这是一份覆盖 SF 所有受支持 LLM providers 的分步配置指南。如果你已经运行过 onboarding 向导（`sf config`）并选择了 provider，很可能已经配置完成，可以在会话中用 `/model` 检查。
## 目录
@ -64,7 +64,7 @@
export ANTHROPIC_API_KEY="sk-ant-..."
```
或者运行 `gsd config`，在提示时粘贴 key。
或者运行 `sf config`，在提示时粘贴 key。
**获取 key：** [console.anthropic.com/settings/keys](https://console.anthropic.com/settings/keys)
@ -76,7 +76,7 @@ export ANTHROPIC_API_KEY="sk-ant-..."
# 安装 Claude Code CLI（见 https://docs.anthropic.com/en/docs/claude-code）
claude
# 按提示登录，然后启动 SF
gsd
sf
```
SF 会检测你本地的 Claude Code 安装，并把它作为已认证的 Anthropic surface 使用。这是 Anthropic 订阅用户符合 TOS 的方式，SF 不会直接处理你的订阅凭据。
@ -94,10 +94,10 @@ SF 会检测你本地的 Claude Code 安装，并把它作为已认证的 Anthro
你也可以在 SF 会话中手动触发：
```bash
/gsd mcp init
/sf mcp init
```
这会在项目的 `.mcp.json` 中写入（或更新）`gsd-workflow` 条目。Claude Code 会在下一次启动会话时自动发现这个文件。
这会在项目的 `.mcp.json` 中写入（或更新）`sf-workflow` 条目。Claude Code 会在下一次启动会话时自动发现这个文件。
**手动配置**
@ -106,24 +106,24 @@ SF 会检测你本地的 Claude Code 安装，并把它作为已认证的 Anthro
```json
{
"mcpServers": {
"gsd": {
"sf": {
"command": "npx",
"args": ["gsd-mcp-server"],
"args": ["sf-mcp-server"],
"env": {
"SF_CLI_PATH": "/path/to/gsd"
"SF_CLI_PATH": "/path/to/sf"
}
}
}
}
```
如果 `gsd-mcp-server` 已经全局安装：
如果 `sf-mcp-server` 已经全局安装：
```json
{
"mcpServers": {
"gsd": {
"command": "gsd-mcp-server"
"sf": {
"command": "sf-mcp-server"
}
}
}
@ -140,7 +140,7 @@ MCP server 会暴露 SF 的完整 workflow 工具面：milestone planning、task
在 SF 会话里检查 MCP server 是否可达：
```bash
/gsd mcp status
/sf mcp status
```
<a id="openai"></a>
@ -150,7 +150,7 @@ MCP server 会暴露 SF 的完整 workflow 工具面：milestone planning、task
export OPENAI_API_KEY="sk-..."
```
或者运行 `gsd config`，选择 “Paste an API key” 然后选择 “OpenAI”。
或者运行 `sf config`，选择 “Paste an API key” 然后选择 “OpenAI”。
**获取 key：** [platform.openai.com/api-keys](https://platform.openai.com/api-keys)
@ -178,7 +178,7 @@ OpenRouter 通过单个 API key 聚合了多个 providers 的 200+ models。
export OPENROUTER_API_KEY="sk-or-..."
```
或者运行 `gsd config`，选择 “Paste an API key” 然后选择 “OpenRouter”。
或者运行 `sf config`，选择 “Paste an API key” 然后选择 “OpenRouter”。
**第 3 步：切换到 OpenRouter model**
@ -186,7 +186,7 @@ export OPENROUTER_API_KEY="sk-or-..."
**可选：通过 `models.json` 添加自定义 OpenRouter models**
如果你想使用不在内置列表中的 model，可把它写进 `~/.gsd/agent/models.json`：
如果你想使用不在内置列表中的 model，可把它写进 `~/.sf/agent/models.json`：
```json
{
@ -268,7 +268,7 @@ export MISTRAL_API_KEY="..."
使用 OAuth，通过浏览器登录：
```bash
gsd config
sf config
# 选择 "Sign in with your browser" → "GitHub Copilot"
```
@ -320,7 +320,7 @@ export AZURE_OPENAI_API_KEY="..."
本地 providers 运行在你的机器上。因为 SF 需要知道 endpoint URL 和可用 models，所以它们都要求配置 `models.json`。
**配置文件位置：** `~/.gsd/agent/models.json`
**配置文件位置：** `~/.sf/agent/models.json`
每次打开 `/model` 时，这个文件都会自动重新加载，无需重启。
@ -344,7 +344,7 @@ ollama pull llama3.1:8b
ollama pull qwen2.5-coder:7b
```
**第 3 步：创建 `~/.gsd/agent/models.json`**
**第 3 步：创建 `~/.sf/agent/models.json`**
```json
{
@ -389,7 +389,7 @@ ollama pull qwen2.5-coder:7b
在 LM Studio 中进入 “Local Server” 标签页，加载一个 model，然后点击 “Start Server”。默认端口为 1234。
**第 3 步：创建 `~/.gsd/agent/models.json`**
**第 3 步：创建 `~/.sf/agent/models.json`**
```json
{
@ -486,12 +486,12 @@ model `id` 必须与 `vllm serve` 启动时传入的 `--model` 参数完全一
**最快路径：使用 onboarding 向导**
```bash
gsd config
sf config
# 选择 "Paste an API key" → "Custom (OpenAI-compatible)"
# 输入：base URL、API key、model ID
```
这会自动帮你写好 `~/.gsd/agent/models.json`。
这会自动帮你写好 `~/.sf/agent/models.json`。
**手动配置：**
@ -562,7 +562,7 @@ gsd config
**原因：** key 虽然设在 shell 中，但 SF 看不到。
**解决：** 确认你是在同一个终端里 `export` 了该环境变量并运行 `gsd`。或者直接用 `gsd config` 把 key 保存进 `~/.gsd/agent/auth.json`，这样就能跨会话持久化。
**解决：** 确认你是在同一个终端里 `export` 了该环境变量并运行 `sf`。或者直接用 `sf config` 把 key 保存进 `~/.sf/agent/auth.json`，这样就能跨会话持久化。
### OpenRouter models 没出现在 `/model`
@ -572,7 +572,7 @@ gsd config
```bash
export OPENROUTER_API_KEY="sk-or-..."
gsd
sf
```
### Ollama 返回空响应
@ -653,7 +653,7 @@ ollama pull llama3.1:8b
1. **启动 SF：**
```bash
gsd
sf
```
2. **检查可用 models：**
@ -671,7 +671,7 @@ ollama pull llama3.1:8b
如果 model 没有出现，请检查：
- 当前 shell 中是否设置了对应环境变量
- `models.json` 是否是合法 JSON（可执行 `cat ~/.gsd/agent/models.json | python3 -m json.tool`）
- `models.json` 是否是合法 JSON（可执行 `cat ~/.sf/agent/models.json | python3 -m json.tool`）
- 本地 providers 的 server 是否已经运行
如果还需要更多帮助，请查看 [故障排查](./troubleshooting.md)，或者在会话中运行 `/gsd doctor`。
如果还需要更多帮助，请查看 [故障排查](./troubleshooting.md)，或者在会话中运行 `/sf doctor`。

20
docs/zh-CN/user-docs/remote-questions.md
View file

@ -7,7 +7,7 @@
### Discord
```
/gsd remote discord
/sf remote discord
```
配置向导会：
@ -17,7 +17,7 @@
3. 列出 bot 当前加入的服务器（或让你选择）
4. 列出所选服务器中的文本频道
5. 发送一条测试消息以确认权限
6. 把配置保存到 `~/.gsd/PREFERENCES.md`
6. 把配置保存到 `~/.sf/PREFERENCES.md`
**Bot 要求：**
@ -32,7 +32,7 @@
### Slack
```
/gsd remote slack
/sf remote slack
```
配置向导会：
@ -52,7 +52,7 @@
### Telegram
```
/gsd remote telegram
/sf remote telegram
```
配置向导会：
@ -71,7 +71,7 @@
## 配置
远程提问配置保存在 `~/.gsd/PREFERENCES.md`：
远程提问配置保存在 `~/.sf/PREFERENCES.md`：
```yaml
remote_questions:
@ -113,11 +113,11 @@ remote_questions:
| 命令 | 说明 |
|------|------|
| `/gsd remote` | 显示远程提问菜单和当前状态 |
| `/gsd remote slack` | 配置 Slack 集成 |
| `/gsd remote discord` | 配置 Discord 集成 |
| `/gsd remote status` | 显示当前配置和最近一次提示状态 |
| `/gsd remote disconnect` | 移除远程提问配置 |
| `/sf remote` | 显示远程提问菜单和当前状态 |
| `/sf remote slack` | 配置 Slack 集成 |
| `/sf remote discord` | 配置 Discord 集成 |
| `/sf remote status` | 显示当前配置和最近一次提示状态 |
| `/sf remote disconnect` | 移除远程提问配置 |
## Discord 与 Slack 功能对比

20
docs/zh-CN/user-docs/skills.md
View file

@ -15,7 +15,7 @@ SF 会按优先级顺序从两个位置读取技能：
如果出现同名技能，全局技能优先于项目技能。
> **从 `~/.gsd/agent/skills/` 迁移：** 升级后首次启动时，SF 会自动把旧版 `~/.gsd/agent/skills/` 中的技能复制到 `~/.agents/skills/`。旧目录会保留，以兼容旧流程。
> **从 `~/.sf/agent/skills/` 迁移：** 升级后首次启动时，SF 会自动把旧版 `~/.sf/agent/skills/` 中的技能复制到 `~/.agents/skills/`。旧目录会保留，以兼容旧流程。
## 安装技能
@ -40,9 +40,9 @@ npx skills update
### 入门技能目录
在执行 `gsd init` 时，SF 会检测项目技术栈并推荐合适的技能包。对于 brownfield 项目，检测是自动的；对于 greenfield 项目，则由用户选择技术栈。
在执行 `sf init` 时，SF 会检测项目技术栈并推荐合适的技能包。对于 brownfield 项目，检测是自动的；对于 greenfield 项目，则由用户选择技术栈。
这个精选目录维护在 `src/resources/extensions/gsd/skill-catalog.ts`。每一条目都会把一个技术栈映射到一个 skills.sh 仓库，以及其中的具体技能名称。
这个精选目录维护在 `src/resources/extensions/sf/skill-catalog.ts`。每一条目都会把一个技术栈映射到一个 skills.sh 仓库，以及其中的具体技能名称。
#### 可用技能包
@ -78,7 +78,7 @@ npx skills update
### 维护目录
技能目录定义位于 [`src/resources/extensions/gsd/skill-catalog.ts`](../../../src/resources/extensions/gsd/skill-catalog.ts)。新增或更新一个技能包时：
技能目录定义位于 [`src/resources/extensions/sf/skill-catalog.ts`](../../../src/resources/extensions/sf/skill-catalog.ts)。新增或更新一个技能包时：
1. 在 `SKILL_CATALOG` 数组中新增一个 `SkillPack` 条目，包含 `repo`、`skills` 和匹配条件
2. 基于语言检测做匹配时，使用 `matchLanguages`（取值来自 `detection.ts` 中的 `LANGUAGE_MAP`）
@ -161,13 +161,13 @@ SF 会跨自动模式会话跟踪技能表现，并提供健康度数据，帮
### 技能健康度面板
通过 `/gsd skill-health` 查看技能表现：
通过 `/sf skill-health` 查看技能表现：
```
/gsd skill-health # 总览表：名称、使用次数、成功率、token、趋势、最近使用时间
/gsd skill-health rust-core # 查看单个技能的详细信息
/gsd skill-health --stale 30 # 查看 30+ 天未使用的技能
/gsd skill-health --declining # 查看成功率在下降的技能
/sf skill-health # 总览表：名称、使用次数、成功率、token、趋势、最近使用时间
/sf skill-health rust-core # 查看单个技能的详细信息
/sf skill-health --stale 30 # 查看 30+ 天未使用的技能
/sf skill-health --declining # 查看成功率在下降的技能
```
该面板会标出可能需要关注的技能：
@ -190,6 +190,6 @@ skill_staleness_days: 60 # 默认 60；设为 0 表示关闭
### Heal-Skill（单元后分析）
如果把它配置为 post-unit hook，SF 可以分析 agent 在执行中是否偏离了某个技能的指令。如果检测到明显漂移（例如 API 模式过时、指导错误），它会把建议修复写到 `.gsd/skill-review-queue.md`，供人工审核。
如果把它配置为 post-unit hook，SF 可以分析 agent 在执行中是否偏离了某个技能的指令。如果检测到明显漂移（例如 API 模式过时、指导错误），它会把建议修复写到 `.sf/skill-review-queue.md`，供人工审核。
一个关键设计原则是：技能**永远不会被自动修改**。研究表明，人工策展的技能明显优于自动生成技能，因此保留人工审核是必要的。

14
docs/zh-CN/user-docs/token-optimization.md
View file

@ -168,7 +168,7 @@ Tasks 会通过分析 task plan 来分类：
## 自适应学习（Routing History）
SF 会随着时间推移记录每个 tier 分配的成功 / 失败情况，并据此调整未来的分类。它默认自动生效，并持久化在 `.gsd/routing-history.json` 中。
SF 会随着时间推移记录每个 tier 分配的成功 / 失败情况，并据此调整未来的分类。它默认自动生效，并持久化在 `.sf/routing-history.json` 中。
### 工作方式
@ -179,12 +179,12 @@ SF 会随着时间推移记录每个 tier 分配的成功 / 失败情况，并
### 用户反馈
你可以通过 `/gsd rate` 为最近完成的工作单元提交反馈：
你可以通过 `/sf rate` 为最近完成的工作单元提交反馈：
```
/gsd rate over # model 太强了，下次更倾向便宜一点
/gsd rate ok # model 选得合适，不调整
/gsd rate under # model 太弱了，下次更倾向强一点
/sf rate over # model 太强了，下次更倾向便宜一点
/sf rate ok # model 选得合适，不调整
/sf rate under # model 太弱了，下次更倾向强一点
```
这些反馈的权重是自动结果的 2 倍。要求 dynamic routing 已启用（最近完成的单元必须带有 tier 数据）。
@ -193,7 +193,7 @@ SF 会随着时间推移记录每个 tier 分配的成功 / 失败情况，并
```bash
# Routing history 按项目存储
.gsd/routing-history.json
.sf/routing-history.json
# 清空历史以重置自适应学习
# （通过 routing-history 模块 API 完成）
@ -312,7 +312,7 @@ context_management:
*引入于 v2.59.0*
当自动模式在 phases 之间切换（research → planning → execution）时，系统会把结构化 JSON anchors 写到 `.gsd/milestones/<mid>/anchors/<phase>.json`。下游 prompt builders 会自动注入这些 anchors，让下一阶段继承前一阶段的意图、决策、阻塞点和下一步，而不必重新从 artifact 文件里推断。
当自动模式在 phases 之间切换（research → planning → execution）时，系统会把结构化 JSON anchors 写到 `.sf/milestones/<mid>/anchors/<phase>.json`。下游 prompt builders 会自动注入这些 anchors，让下一阶段继承前一阶段的意图、决策、阻塞点和下一步，而不必重新从 artifact 文件里推断。
这能减少上下文漂移，也就是企业级 agent 失败案例中最常见的一类问题：agent 在 phase 边界上丢失了之前的决策脉络。

80
docs/zh-CN/user-docs/troubleshooting.md
View file

@ -1,11 +1,11 @@
# 故障排查
## `/gsd doctor`
## `/sf doctor`
内置诊断工具会校验 `.gsd/` 的完整性：
内置诊断工具会校验 `.sf/` 的完整性：
```
/gsd doctor
/sf doctor
```
它会检查：
@ -27,13 +27,13 @@
- 崩溃后的缓存过期：内存中的文件列表没有反映新产物
- LLM 没有生成预期的 artifact 文件
**解决：** 先运行 `/gsd doctor` 修复状态，然后执行 `/gsd auto` 恢复。如果问题持续存在，检查预期 artifact 文件是否确实已经写到磁盘。
**解决：** 先运行 `/sf doctor` 修复状态，然后执行 `/sf auto` 恢复。如果问题持续存在，检查预期 artifact 文件是否确实已经写到磁盘。
### 自动模式因 “Loop detected” 停止
**原因：** 同一个单元连续两次没有生成预期 artifact。
**解决：** 检查 task plan 是否足够清晰。如果 plan 存在歧义，先手动澄清，再执行 `/gsd auto` 恢复。
**解决：** 检查 task plan 是否足够清晰。如果 plan 存在歧义，先手动澄清，再执行 `/sf auto` 恢复。
### Worktree 中出现了错误文件
@ -43,9 +43,9 @@
**解决：** 该问题已在 v2.14+ 修复。如果你仍在旧版本，请更新。现在 dispatch prompt 已包含明确的工作目录指令。
### 安装后出现 `command not found: gsd`
### 安装后出现 `command not found: sf`
**症状：** `npm install -g sf-run` 成功，但系统找不到 `gsd`。
**症状：** `npm install -g sf-run` 成功，但系统找不到 `sf`。
**原因：** npm 的全局 bin 目录没有加入 shell 的 `$PATH`。
@ -61,13 +61,13 @@ echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```
**临时方案：** 直接执行 `npx sf-run`，或使用 `$(npm prefix -g)/bin/gsd`。
**临时方案：** 直接执行 `npx sf-run`，或使用 `$(npm prefix -g)/bin/sf`。
**常见原因：**
- **Homebrew Node**：理论上 `/opt/homebrew/bin` 应该在 PATH 里，但如果 shell profile 没有初始化 Homebrew，就可能缺失
- **版本管理器（nvm、fnm、mise）**：全局 bin 路径是按版本区分的，需确保版本管理器正确初始化
- **oh-my-zsh**：`gitfast` 插件会把 `gsd` alias 到 `git svn dcommit`。可通过 `alias gsd` 检查，并在需要时取消 alias
- **oh-my-zsh**：`gitfast` 插件会把 `sf` alias 到 `git svn dcommit`。可通过 `alias sf` 检查，并在需要时取消 alias
### `npm install -g sf-run` 失败
@ -99,7 +99,7 @@ models:
- openrouter/minimax/minimax-m2.5
```
**Headless 模式：** `gsd headless auto` 在进程崩溃时会自动重启整个进程（默认 3 次，带指数退避）。与 provider 错误自动恢复配合后，能支持真正的夜间无人值守运行。
**Headless 模式：** `sf headless auto` 在进程崩溃时会自动重启整个进程（默认 3 次，带指数退避）。与 provider 错误自动恢复配合后，能支持真正的夜间无人值守运行。
常见的 provider 配置问题（role 错误、streaming 错误、model ID 不匹配）见 [Provider 设置指南：常见坑点](./providers.md#common-pitfalls)。
@ -107,30 +107,30 @@ models:
**症状：** 自动模式因 “Budget ceiling reached” 暂停。
**解决：** 提高偏好设置中的 `budget_ceiling`，或者切换到 `budget` token profile 降低每个工作单元成本，然后再执行 `/gsd auto` 恢复。
**解决：** 提高偏好设置中的 `budget_ceiling`，或者切换到 `budget` token profile 降低每个工作单元成本，然后再执行 `/sf auto` 恢复。
### 过期锁文件
**症状：** 自动模式无法启动，提示另一个会话正在运行。
**解决：** SF 会自动检测过期锁：如果持有锁的 PID 已死亡，则在下次 `/gsd auto` 时清理并重新获取锁。它也会处理 `proper-lockfile` 崩溃后遗留的 `.gsd.lock/` 目录。如果自动恢复失败，可手动删除 `.gsd/auto.lock` 和 `.gsd.lock/`：
**解决：** SF 会自动检测过期锁：如果持有锁的 PID 已死亡，则在下次 `/sf auto` 时清理并重新获取锁。它也会处理 `proper-lockfile` 崩溃后遗留的 `.sf.lock/` 目录。如果自动恢复失败，可手动删除 `.sf/auto.lock` 和 `.sf.lock/`：
```bash
rm -f .gsd/auto.lock
rm -rf "$(dirname .gsd)/.gsd.lock"
rm -f .sf/auto.lock
rm -rf "$(dirname .sf)/.sf.lock"
```
### Git merge 冲突
**症状：** Worktree merge 在 `.gsd/` 文件上失败。
**症状：** Worktree merge 在 `.sf/` 文件上失败。
**解决：** SF 会自动解决 `.gsd/` 运行时文件上的冲突。对于代码文件的内容冲突，LLM 会先获得一次 fix-merge 会话进行自动修复；若失败，则需要手动解决。
**解决：** SF 会自动解决 `.sf/` 运行时文件上的冲突。对于代码文件的内容冲突，LLM 会先获得一次 fix-merge 会话进行自动修复；若失败，则需要手动解决。
### Pre-dispatch 提示 milestone integration branch 已不存在
**症状：** 自动模式或 `/gsd doctor` 报告某个 milestone 记录的 integration branch 已经不在 git 中。
**症状：** 自动模式或 `/sf doctor` 报告某个 milestone 记录的 integration branch 已经不在 git 中。
**这意味着什么：** 该 milestone 的 `.gsd/milestones/<MID>/<MID>-META.json` 里仍然记录着启动时的 branch，但该 branch 之后被重命名或删除了。
**这意味着什么：** 该 milestone 的 `.sf/milestones/<MID>/<MID>-META.json` 里仍然记录着启动时的 branch，但该 branch 之后被重命名或删除了。
**当前行为：**
@ -138,17 +138,17 @@ rm -rf "$(dirname .gsd)/.gsd.lock"
- 安全回退的顺序是：
- 显式配置且存在的 `git.main_branch`
- 仓库自动检测到的默认 integration branch（例如 `main` 或 `master`）
- 在这种情况下，`/gsd doctor` 会给出 warning，而 `/gsd doctor fix` 会把过期的 metadata 改写为当前有效 branch
- 在这种情况下，`/sf doctor` 会给出 warning，而 `/sf doctor fix` 会把过期的 metadata 改写为当前有效 branch
- 如果无法确定安全回退 branch，SF 仍会阻止继续运行
**解决：**
- 先执行 `/gsd doctor fix`，在安全回退很明显时自动改写过期 metadata
- 先执行 `/sf doctor fix`，在安全回退很明显时自动改写过期 metadata
- 如果 SF 仍然阻塞，则请重新创建缺失 branch，或更新 git 偏好设置，让 `git.main_branch` 指向一个真实存在的 branch
### 写 `.gsd/` 文件时出现瞬时 `EBUSY` / `EPERM` / `EACCES`
### 写 `.sf/` 文件时出现瞬时 `EBUSY` / `EPERM` / `EACCES`
**症状：** 在 Windows 上，自动模式或 doctor 在更新 `.gsd/` 文件时偶发 `EBUSY`、`EPERM` 或 `EACCES`。
**症状：** 在 Windows 上，自动模式或 doctor 在更新 `.sf/` 文件时偶发 `EBUSY`、`EPERM` 或 `EACCES`。
**原因：** 杀毒软件、索引器、编辑器或文件监视器可能会在 SF 执行原子 rename 的瞬间，短暂锁住目标文件或临时文件。
@ -158,11 +158,11 @@ rm -rf "$(dirname .gsd)/.gsd.lock"
- 重新执行操作；大多数瞬时锁竞争会很快自行解除
- 如果错误持续，关闭可能占用该文件的工具后再试
- 如果反复失败，运行 `/gsd doctor`，确认仓库状态依旧健康，并记录具体路径与错误码
- 如果反复失败，运行 `/sf doctor`，确认仓库状态依旧健康，并记录具体路径与错误码
### Node v24 Web 启动失败
**症状：** 在 Node v24 上执行 `gsd --web` 时，报 `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`。
**症状：** 在 Node v24 上执行 `sf --web` 时，报 `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`。
**原因：** Node v24 修改了对 `node_modules` 的 type stripping 行为，导致 Next.js Web 构建失败。
@ -170,7 +170,7 @@ rm -rf "$(dirname .gsd)/.gsd.lock"
### 孤儿 Web server 进程
**症状：** `gsd --web` 因端口 3000 已被占用而失败，但实际上并没有运行中的 SF 会话。
**症状：** `sf --web` 因端口 3000 已被占用而失败，但实际上并没有运行中的 SF 会话。
**原因：** 上一次 Web server 退出时未能清理进程。
@ -200,13 +200,13 @@ rm -rf "$(dirname .gsd)/.gsd.lock"
**常见原因：**
- 当前项目里不存在 `.mcp.json` 或 `.gsd/mcp.json`
- 当前项目里不存在 `.mcp.json` 或 `.sf/mcp.json`
- 配置文件不是合法 JSON
- 你是在另一个项目目录中配置的 server，但当前启动 SF 的目录不同
**解决：**
- 把 server 配置加到 `.mcp.json` 或 `.gsd/mcp.json`
- 把 server 配置加到 `.mcp.json` 或 `.sf/mcp.json`
- 确认文件能被正常解析为 JSON
- 重新执行 `mcp_servers(refresh=true)`
@ -275,11 +275,11 @@ rm -rf "$(dirname .gsd)/.gsd.lock"
- 把所需环境变量写进 MCP 配置的 `env` 块
- 有必要时，在 server 定义里显式设置 `cwd`
### Session lock 被另一个终端中的 `/gsd` 抢走
### Session lock 被另一个终端中的 `/sf` 抢走
**症状：** 在第二个终端运行 `/gsd`（step mode）时，正在运行的自动模式会话失去了锁。
**症状：** 在第二个终端运行 `/sf`（step mode）时，正在运行的自动模式会话失去了锁。
**解决：** 已在 v2.36.0 修复。现在裸 `/gsd` 不会再从运行中的自动模式会话手里抢 session lock。升级到最新版本。
**解决：** 已在 v2.36.0 修复。现在裸 `/sf` 不会再从运行中的自动模式会话手里抢 session lock。升级到最新版本。
### Worktree 中的提交落到了 main，而不是 `milestone/<MID>` 分支
@ -300,34 +300,34 @@ rm -rf "$(dirname .gsd)/.gsd.lock"
### 重置自动模式状态
```bash
rm .gsd/auto.lock
rm .gsd/completed-units.json
rm .sf/auto.lock
rm .sf/completed-units.json
```
然后执行 `/gsd auto`，从当前磁盘状态重新开始。
然后执行 `/sf auto`，从当前磁盘状态重新开始。
### 重置路由历史
如果自适应模型路由给出了糟糕的结果，可以清空路由历史：
```bash
rm .gsd/routing-history.json
rm .sf/routing-history.json
```
### 完整重建状态
```
/gsd doctor
/sf doctor
```
Doctor 会从磁盘上的 plan 和 roadmap 文件重建 `STATE.md`，并修复检测到的不一致项。
## 获取帮助
- **GitHub Issues：** [github.com/gsd-build/SF/issues](https://github.com/gsd-build/SF/issues)
- **Dashboard：** `Ctrl+Alt+G` 或 `/gsd status`，查看实时诊断信息
- **Forensics：** `/gsd forensics`，用于对自动模式失败做结构化事后分析
- **Session logs：** `.gsd/activity/` 中包含用于崩溃取证的 JSONL 会话转储
- **GitHub Issues：** [github.com/sf-build/SF/issues](https://github.com/sf-build/SF/issues)
- **Dashboard：** `Ctrl+Alt+G` 或 `/sf status`，查看实时诊断信息
- **Forensics：** `/sf forensics`，用于对自动模式失败做结构化事后分析
- **Session logs：** `.sf/activity/` 中包含用于崩溃取证的 JSONL 会话转储
## iTerm2 专属问题
@ -363,7 +363,7 @@ Doctor 会从磁盘上的 plan 和 roadmap 文件重建 `STATE.md`，并修复
**症状：** `gsd_decision_save`（及其别名 `gsd_save_decision`）、`gsd_requirement_update`（及其别名 `gsd_update_requirement`）或 `gsd_summary_save`（及其别名 `gsd_save_summary`）报这个错误。
**原因：** SQLite 数据库未初始化。这个问题会出现在 v2.29 之前的手动 `/gsd` 会话（非自动模式）中。
**原因：** SQLite 数据库未初始化。这个问题会出现在 v2.29 之前的手动 `/sf` 会话（非自动模式）中。
**解决：** 已在 v2.29+ 修复。现在数据库会在第一次 tool call 时自动初始化。升级到最新版本。

6
docs/zh-CN/user-docs/visualizer.md
View file

@ -7,7 +7,7 @@
## 打开可视化器
```
/gsd visualize
/sf visualize
```
或者配置为在 milestone 完成后自动显示：
@ -59,7 +59,7 @@ S01 ──→ S02 ──→ S04
- **按 slice**：每个 slice 的成本以及累计总额
- **按模型**：哪些模型消耗了最多预算
数据来自 `.gsd/metrics.json`。
数据来自 `.sf/metrics.json`。
### 4. 时间线
@ -89,7 +89,7 @@ S01 ──→ S02 ──→ S04
## HTML 导出（v2.26）
如果需要在终端外部分享报告，可以使用 `/gsd export --html`。它会在 `.gsd/reports/` 中生成一个自包含的 HTML 文件，包含与 TUI 可视化器相同的数据：进度树、依赖图（SVG DAG）、成本 / Token 柱状图、执行时间线、变更日志和知识库。所有 CSS 和 JS 都会内联，无外部依赖，也可以在任意浏览器中打印为 PDF。
如果需要在终端外部分享报告，可以使用 `/sf export --html`。它会在 `.sf/reports/` 中生成一个自包含的 HTML 文件，包含与 TUI 可视化器相同的数据：进度树、依赖图（SVG DAG）、成本 / Token 柱状图、执行时间线、变更日志和知识库。所有 CSS 和 JS 都会内联，无外部依赖，也可以在任意浏览器中打印为 PDF。
自动生成的 `index.html` 会集中列出所有报告，并显示跨 milestones 的推进指标。

4
docs/zh-CN/user-docs/web-interface.md
View file

@ -7,7 +7,7 @@ SF 提供了基于浏览器的 Web 界面，用于项目管理、实时进度监
## 快速开始
```bash
gsd --web
sf --web
```
这会启动一个本地 Web 服务器，并在默认浏览器中打开 SF 仪表板。
@ -15,7 +15,7 @@ gsd --web
### CLI 参数（v2.42.0）
```bash
gsd --web --host 0.0.0.0 --port 8080 --allowed-origins "https://example.com"
sf --web --host 0.0.0.0 --port 8080 --allowed-origins "https://example.com"
```
| 参数 | 默认值 | 说明 |

42
docs/zh-CN/user-docs/working-in-teams.md
View file

@ -9,7 +9,7 @@ SF 支持多人并行工作流，让多个开发者可以同时在同一个仓
为团队使用配置 SF 的最简单方法，是在项目偏好中设置 `mode: team`。这会一次性开启唯一 milestone ID、推送分支和预合并检查：
```yaml
# .gsd/PREFERENCES.md（项目级，提交到 git）
# .sf/PREFERENCES.md（项目级，提交到 git）
---
version: 1
mode: team
@ -26,24 +26,24 @@ mode: team
```bash
# ── SF：运行时 / 临时文件（按开发者、按会话隔离）──────
.gsd/auto.lock
.gsd/completed-units.json
.gsd/STATE.md
.gsd/metrics.json
.gsd/activity/
.gsd/runtime/
.gsd/worktrees/
.gsd/milestones/**/continue.md
.gsd/milestones/**/*-CONTINUE.md
.sf/auto.lock
.sf/completed-units.json
.sf/STATE.md
.sf/metrics.json
.sf/activity/
.sf/runtime/
.sf/worktrees/
.sf/milestones/**/continue.md
.sf/milestones/**/*-CONTINUE.md
```
**会共享的内容**（提交到 git）：
- `.gsd/PREFERENCES.md`：项目偏好
- `.gsd/PROJECT.md`：持续维护的项目描述
- `.gsd/REQUIREMENTS.md`：需求契约
- `.gsd/DECISIONS.md`：架构决策
- `.gsd/milestones/`：roadmaps、plans、summaries 和 research
- `.sf/PREFERENCES.md`：项目偏好
- `.sf/PROJECT.md`：持续维护的项目描述
- `.sf/REQUIREMENTS.md`：需求契约
- `.sf/DECISIONS.md`：架构决策
- `.sf/milestones/`：roadmaps、plans、summaries 和 research
**仅保留本地的内容**（gitignore）：
@ -52,7 +52,7 @@ mode: team
### 3. 提交偏好设置
```bash
git add .gsd/PREFERENCES.md
git add .sf/PREFERENCES.md
git commit -m "chore: enable SF team workflow"
```
@ -65,21 +65,21 @@ git:
commit_docs: false
```
这会把整个 `.gsd/` 加入 `.gitignore`，让所有产物都保留在本地。这样使用 SF 的开发者仍然能获得结构化规划的好处，而不会影响不使用 SF 的同事。
这会把整个 `.sf/` 加入 `.gitignore`，让所有产物都保留在本地。这样使用 SF 的开发者仍然能获得结构化规划的好处，而不会影响不使用 SF 的同事。
## 迁移现有项目
如果你当前项目里对 `.gsd/` 做了整目录忽略：
如果你当前项目里对 `.sf/` 做了整目录忽略：
1. 确保当前没有进行中的 milestones（工作区状态干净）
2. 按上面的选择性规则更新 `.gitignore`
3. 在 `.gsd/PREFERENCES.md` 中添加 `unique_milestone_ids: true`
3. 在 `.sf/PREFERENCES.md` 中添加 `unique_milestone_ids: true`
4. 如有需要，重命名现有 milestones 以使用唯一 ID：
```
I have turned on unique milestone ids, please update all old milestone
ids to use this new format e.g. M001-abc123 where abc123 is a random
6 char lowercase alpha numeric string. Update all references in all
.gsd file contents, file names and directory names. Validate your work
.sf file contents, file names and directory names. Validate your work
once done to ensure referential integrity.
```
5. 提交修改
@ -88,7 +88,7 @@ git:
多个开发者可以同时对不同 milestones 运行自动模式。每个开发者都会：
- 获得自己的 worktree（`.gsd/worktrees/<MID>/`，已加入 gitignore）
- 获得自己的 worktree（`.sf/worktrees/<MID>/`，已加入 gitignore）
- 在独立的 `milestone/<MID>` 分支上工作
- 独立地 squash merge 回主分支

10
gitbook/README.md
View file

@ -22,7 +22,7 @@ You can stay hands-on with **step mode** (reviewing each step) or let SF run aut
## Key Features
- **Autonomous execution** — `/gsd auto` runs research, planning, coding, testing, and committing without intervention
- **Autonomous execution** — `/sf auto` runs research, planning, coding, testing, and committing without intervention
- **20+ LLM providers** — Anthropic, OpenAI, Google, OpenRouter, GitHub Copilot, Amazon Bedrock, local models, and more
- **Git isolation** — Each milestone works in its own worktree branch, merged cleanly when done
- **Cost tracking** — Real-time token usage, budget ceilings, and automatic model downgrading
@ -41,10 +41,10 @@ You can stay hands-on with **step mode** (reviewing each step) or let SF run aut
npm install -g sf-run
# Launch
gsd
sf
# Start autonomous mode
/gsd auto
/sf auto
```
See [Installation](getting-started/installation.md) for detailed setup instructions.
@ -53,8 +53,8 @@ See [Installation](getting-started/installation.md) for detailed setup instructi
| Mode | Command | Best For |
|------|---------|----------|
| **Step** | `/gsd` | Staying in the loop, reviewing each step |
| **Auto** | `/gsd auto` | Walking away, overnight builds, batch work |
| **Step** | `/sf` | Staying in the loop, reviewing each step |
| **Auto** | `/sf auto` | Walking away, overnight builds, batch work |
The recommended workflow: run auto mode in one terminal, steer from another. See [Step Mode](core-concepts/step-mode.md) and [Auto Mode](core-concepts/auto-mode.md).

6
gitbook/configuration/custom-models.md
View file

@ -1,11 +1,11 @@
# Custom Models
Define custom models and providers in `~/.gsd/agent/models.json`. This lets you add models not in the default registry — self-hosted endpoints, fine-tuned models, proxies, or new provider releases.
Define custom models and providers in `~/.sf/agent/models.json`. This lets you add models not in the default registry — self-hosted endpoints, fine-tuned models, proxies, or new provider releases.
## File Location
SF looks for models.json at:
1. `~/.gsd/agent/models.json` (primary)
1. `~/.sf/agent/models.json` (primary)
2. `~/.pi/agent/models.json` (fallback)
The file reloads each time you open `/model` — no restart needed.
@ -128,4 +128,4 @@ For providers not built into SF, community extensions add full provider support:
| Extension | Provider | Install |
|-----------|----------|---------|
| `pi-dashscope` | Alibaba DashScope (Qwen3, GLM-5, etc.) | `gsd install npm:pi-dashscope` |
| `pi-dashscope` | Alibaba DashScope (Qwen3, GLM-5, etc.) | `sf install npm:pi-dashscope` |

12
gitbook/configuration/git-settings.md
View file

@ -8,7 +8,7 @@ SF supports three isolation modes, configured via `git.isolation` in preferences
| Mode | Working Directory | Branch | Best For |
|------|-------------------|--------|----------|
| `worktree` (default) | `.gsd/worktrees/<MID>/` | `milestone/<MID>` | Most projects — full isolation |
| `worktree` (default) | `.sf/worktrees/<MID>/` | `milestone/<MID>` | Most projects — full isolation |
| `branch` | Project root | `milestone/<MID>` | Submodule-heavy repos |
| `none` | Project root | Current branch | Hot-reload workflows |
@ -69,7 +69,7 @@ git:
main_branch: main # primary branch name
merge_strategy: squash # "squash" or "merge"
isolation: worktree # "worktree", "branch", or "none"
commit_docs: true # commit .gsd/ artifacts to git
commit_docs: true # commit .sf/ artifacts to git
manage_gitignore: true # let SF manage .gitignore
auto_pr: false # create PR on milestone completion
pr_target_branch: develop # PR target branch
@ -94,7 +94,7 @@ Run a script after worktree creation (copy `.env` files, symlink assets, etc.):
```yaml
git:
worktree_post_create: .gsd/hooks/post-worktree-create
worktree_post_create: .sf/hooks/post-worktree-create
```
Example hook:
@ -105,7 +105,7 @@ cp "$SOURCE_DIR/.env" "$WORKTREE_DIR/.env"
ln -sf "$SOURCE_DIR/assets" "$WORKTREE_DIR/assets"
```
## Keeping `.gsd/` Local
## Keeping `.sf/` Local
For teams where only some members use SF:
@ -114,7 +114,7 @@ git:
commit_docs: false
```
This adds `.gsd/` to `.gitignore` entirely. You get structured planning without affecting teammates who don't use SF.
This adds `.sf/` to `.gitignore` entirely. You get structured planning without affecting teammates who don't use SF.
## Commit Format
@ -145,4 +145,4 @@ SF automatically recovers from common git issues:
- **Stale lock files** — removes `index.lock` from crashed processes
- **Orphaned worktrees** — detects and cleans up abandoned worktrees
Run `/gsd doctor` to check git health manually.
Run `/sf doctor` to check git health manually.

6
gitbook/configuration/mcp-servers.md
View file

@ -7,7 +7,7 @@ SF can connect to external MCP (Model Context Protocol) servers for local tools,
SF reads MCP config from these project-local paths:
- `.mcp.json` — repo-shared config (safe to commit)
- `.gsd/mcp.json` — local-only config (not shared)
- `.sf/mcp.json` — local-only config (not shared)
If both exist, server names are merged and the first definition found wins.
@ -61,5 +61,5 @@ After adding config, verify from a SF session:
- Use **absolute paths** for executables and scripts
- Set required **environment variables** directly in the MCP config's `env` block
- Use `.mcp.json` for team-shared servers; `.gsd/mcp.json` for machine-local ones
- If a server depends on local paths or personal secrets, keep it in `.gsd/mcp.json`
- Use `.mcp.json` for team-shared servers; `.sf/mcp.json` for machine-local ones
- If a server depends on local paths or personal secrets, keep it in `.sf/mcp.json`

12
gitbook/configuration/preferences.md
View file

@ -5,17 +5,17 @@ SF preferences live in YAML frontmatter markdown files. You can configure them g
## Managing Preferences
```
/gsd prefs # open the global preferences wizard
/gsd prefs project # open the project preferences wizard
/gsd prefs status # show current values and where they come from
/sf prefs # open the global preferences wizard
/sf prefs project # open the project preferences wizard
/sf prefs status # show current values and where they come from
```
## Preference Files
| Scope | Path | Applies To |
|-------|------|-----------|
| Global | `~/.gsd/PREFERENCES.md` | All projects |
| Project | `.gsd/PREFERENCES.md` | Current project only |
| Global | `~/.sf/PREFERENCES.md` | All projects |
| Project | `.sf/PREFERENCES.md` | Current project only |
**How they merge:**
- **Scalar fields** (`budget_ceiling`, `token_profile`): project wins if defined
@ -219,7 +219,7 @@ custom_instructions:
- "Prefer functional patterns over classes"
```
For project-specific patterns, use `.gsd/KNOWLEDGE.md` instead — it's injected into every agent prompt automatically.
For project-specific patterns, use `.sf/KNOWLEDGE.md` instead — it's injected into every agent prompt automatically.
### `context_pause_threshold`

24
gitbook/configuration/providers.md
View file

@ -1,6 +1,6 @@
# Provider Setup
Step-by-step setup instructions for every LLM provider SF supports. If you ran the onboarding wizard (`gsd config`) and picked a provider, you may already be configured — check with `/model` inside a session.
Step-by-step setup instructions for every LLM provider SF supports. If you ran the onboarding wizard (`sf config`) and picked a provider, you may already be configured — check with `/model` inside a session.
## Quick Reference
@ -30,7 +30,7 @@ Step-by-step setup instructions for every LLM provider SF supports. If you ran t
**Option A — Browser sign-in (recommended):**
```bash
gsd config
sf config
# Choose "Sign in with your browser" → "Anthropic (Claude)"
```
@ -48,7 +48,7 @@ export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
```
Or run `gsd config` and choose "Paste an API key" then "OpenAI".
Or run `sf config` and choose "Paste an API key" then "OpenAI".
### Google Gemini
@ -67,7 +67,7 @@ OpenRouter aggregates 200+ models from multiple providers behind a single API ke
```
3. In SF, type `/model` to select an OpenRouter model (prefixed with `openrouter/`)
To add models not in the built-in list, add them to `~/.gsd/agent/models.json`. See [Custom Models](custom-models.md).
To add models not in the built-in list, add them to `~/.sf/agent/models.json`. See [Custom Models](custom-models.md).
### Groq
@ -92,7 +92,7 @@ export MISTRAL_API_KEY="..."
Uses OAuth — sign in through the browser:
```bash
gsd config
sf config
# Choose "Sign in with your browser" → "GitHub Copilot"
```
@ -132,7 +132,7 @@ export AZURE_OPENAI_API_KEY="..."
## Local Providers
Local providers run on your machine. They require a `models.json` configuration file at `~/.gsd/agent/models.json` because SF needs to know the endpoint URL and available models.
Local providers run on your machine. They require a `models.json` configuration file at `~/.sf/agent/models.json` because SF needs to know the endpoint URL and available models.
The file reloads each time you open `/model` — no restart needed.
@ -149,7 +149,7 @@ The file reloads each time you open `/model` — no restart needed.
ollama pull llama3.1:8b
```
3. Create `~/.gsd/agent/models.json`:
3. Create `~/.sf/agent/models.json`:
```json
{
"providers": {
@ -175,7 +175,7 @@ The file reloads each time you open `/model` — no restart needed.
1. Install [LM Studio](https://lmstudio.ai)
2. Go to "Local Server" tab, load a model, click "Start Server" (default port 1234)
3. Create `~/.gsd/agent/models.json`:
3. Create `~/.sf/agent/models.json`:
```json
{
"providers": {
@ -245,16 +245,16 @@ Any server that implements the OpenAI Chat Completions API can work with SF —
**Quickest path:**
```bash
gsd config
sf config
# Choose "Paste an API key" → "Custom (OpenAI-compatible)"
# Enter: base URL, API key, model ID
```
This writes `~/.gsd/agent/models.json` for you. See [Custom Models](custom-models.md) for manual setup.
This writes `~/.sf/agent/models.json` for you. See [Custom Models](custom-models.md) for manual setup.
## Verifying Your Setup
1. Launch SF: `gsd`
1. Launch SF: `sf`
2. Check available models: `/model`
3. Select your model from the picker
4. Send a test message to confirm it responds
@ -268,7 +268,7 @@ If the model doesn't appear, check:
| Problem | Cause | Fix |
|---------|-------|-----|
| "Authentication failed" with valid key | Key not visible to SF | Export in the same terminal, or save via `gsd config` |
| "Authentication failed" with valid key | Key not visible to SF | Export in the same terminal, or save via `sf config` |
| OpenRouter models not in `/model` | No API key set | Set `OPENROUTER_API_KEY` and restart |
| Ollama returns empty responses | Server not running or model not pulled | Run `ollama serve` and `ollama pull <model>` |
| LM Studio model ID mismatch | ID doesn't match server | Check LM Studio's server tab for the exact identifier |

34
gitbook/core-concepts/auto-mode.md
View file

@ -1,14 +1,14 @@
# Auto Mode
Auto mode is SF's autonomous execution engine. Run `/gsd auto`, walk away, come back to built software with clean git history.
Auto mode is SF's autonomous execution engine. Run `/sf auto`, walk away, come back to built software with clean git history.
## Starting Auto Mode
```
/gsd auto
/sf auto
```
SF reads `.gsd/STATE.md`, determines the next unit of work, creates a fresh AI session with all relevant context, and lets the AI execute. When it finishes, SF reads disk state again and dispatches the next unit. This continues until the milestone is complete.
SF reads `.sf/STATE.md`, determines the next unit of work, creates a fresh AI session with all relevant context, and lets the AI execute. When it finishes, SF reads disk state again and dispatches the next unit. This continues until the milestone is complete.
## The Execution Loop
@ -35,7 +35,7 @@ Press **Escape**. The conversation is preserved. You can interact with the agent
### Resume
```
/gsd auto
/sf auto
```
Auto mode reads disk state and picks up where it left off.
@ -43,7 +43,7 @@ Auto mode reads disk state and picks up where it left off.
### Stop
```
/gsd stop
/sf stop
```
Stops auto mode gracefully. Can be run from a different terminal.
@ -51,7 +51,7 @@ Stops auto mode gracefully. Can be run from a different terminal.
### Steer
```
/gsd steer
/sf steer
```
Modify plan documents during execution without stopping. Changes are picked up at the next phase boundary.
@ -59,7 +59,7 @@ Modify plan documents during execution without stopping. Changes are picked up a
### Capture Thoughts
```
/gsd capture "add rate limiting to API endpoints"
/sf capture "add rate limiting to API endpoints"
```
Fire-and-forget thought capture. Captures are triaged automatically between tasks without pausing execution. See [Captures & Triage](../features/captures.md).
@ -82,9 +82,9 @@ In worktree mode, all commits are squash-merged to main as one clean commit when
## Crash Recovery
If a session dies, the next `/gsd auto` reads the surviving session file, synthesizes a recovery briefing from every tool call that made it to disk, and resumes with full context.
If a session dies, the next `/sf auto` reads the surviving session file, synthesizes a recovery briefing from every tool call that made it to disk, and resumes with full context.
In headless mode (`gsd headless auto`), crashes trigger automatic restart with exponential backoff (5s → 10s → 30s, up to 3 attempts). Combined with crash recovery, this enables true overnight "fire and forget" execution.
In headless mode (`sf headless auto`), crashes trigger automatic restart with exponential backoff (5s → 10s → 30s, up to 3 attempts). Combined with crash recovery, this enables true overnight "fire and forget" execution.
## Provider Error Recovery
@ -151,7 +151,7 @@ Every unit's token usage and cost is captured, broken down by phase, slice, and
## Dashboard
`Ctrl+Alt+G` or `/gsd status` shows real-time progress:
`Ctrl+Alt+G` or `/sf status` shows real-time progress:
- Current milestone, slice, and task
- Auto mode elapsed time and phase
@ -163,21 +163,21 @@ Every unit's token usage and cost is captured, broken down by phase, slice, and
## HTML Reports
After a milestone completes, SF generates a self-contained HTML report in `.gsd/reports/` with project summary, progress tree, dependency graph, cost metrics, timeline, and changelog. Generate manually with:
After a milestone completes, SF generates a self-contained HTML report in `.sf/reports/` with project summary, progress tree, dependency graph, cost metrics, timeline, and changelog. Generate manually with:
```
/gsd export --html
/gsd export --html --all # all milestones
/sf export --html
/sf export --html --all # all milestones
```
## Diagnostic Tools
If auto mode has issues, SF provides two diagnostic tools:
- **`/gsd doctor`** — validates `.gsd/` integrity, checks referential consistency, fixes structural issues
- **`/gsd forensics`** — full post-mortem debugger with anomaly detection, unit traces, metrics analysis, and AI-guided investigation
- **`/sf doctor`** — validates `.sf/` integrity, checks referential consistency, fixes structural issues
- **`/sf forensics`** — full post-mortem debugger with anomaly detection, unit traces, metrics analysis, and AI-guided investigation
```
/gsd doctor
/gsd forensics [optional problem description]
/sf doctor
/sf forensics [optional problem description]
```

12
gitbook/core-concepts/project-structure.md
View file

@ -37,12 +37,12 @@ Examples:
- "Implement JWT middleware"
- "Build the login form component"
## The `.gsd/` Directory
## The `.sf/` Directory
All project state lives on disk in a `.gsd/` directory at your project root:
All project state lives on disk in a `.sf/` directory at your project root:
```
.gsd/
.sf/
PROJECT.md — living description of what the project is
REQUIREMENTS.md — requirement contract (active/validated/deferred)
DECISIONS.md — append-only architectural decisions log
@ -96,9 +96,9 @@ After all slices complete, a **milestone validation** gate checks that success c
SF maintains a knowledge base that persists across sessions. Add rules, patterns, or lessons:
```
/gsd knowledge rule "Always use parameterized queries for database access"
/gsd knowledge pattern "Service classes go in src/services/"
/gsd knowledge lesson "The OAuth flow requires the redirect URL to match exactly"
/sf knowledge rule "Always use parameterized queries for database access"
/sf knowledge pattern "Service classes go in src/services/"
/sf knowledge lesson "The OAuth flow requires the redirect URL to match exactly"
```
This knowledge is injected into every task prompt automatically.

16
gitbook/core-concepts/step-mode.md
View file

@ -5,10 +5,10 @@ Step mode is SF's interactive, one-step-at-a-time workflow. You stay in the loop
## Starting Step Mode
```
/gsd
/sf
```
SF reads the state of your `.gsd/` directory and presents a wizard showing what's completed and what's next. It then executes one unit of work and pauses.
SF reads the state of your `.sf/` directory and presents a wizard showing what's completed and what's next. It then executes one unit of work and pauses.
## How It Works
@ -16,7 +16,7 @@ Step mode adapts to your project's current state:
| State | What Happens |
|-------|-------------|
| No `.gsd/` directory | Starts a discussion flow to capture your project vision |
| No `.sf/` directory | Starts a discussion flow to capture your project vision |
| Milestone exists, no roadmap | Opens a discussion or research phase for the milestone |
| Roadmap exists, slices pending | Plans the next slice or executes the next task |
| Mid-task | Resumes where you left off |
@ -31,10 +31,10 @@ After each unit completes, you see results and decide what to do next. This is i
Between steps, you can:
- **Discuss** — `/gsd discuss` to talk through architecture decisions
- **Skip** — `/gsd skip` to prevent a unit from being dispatched
- **Undo** — `/gsd undo` to revert the last completed unit
- **Switch to auto** — `/gsd auto` to let SF continue autonomously
- **Discuss** — `/sf discuss` to talk through architecture decisions
- **Skip** — `/sf skip` to prevent a unit from being dispatched
- **Undo** — `/sf undo` to revert the last completed unit
- **Switch to auto** — `/sf auto` to let SF continue autonomously
## When to Use Step Mode
@ -48,7 +48,7 @@ Between steps, you can:
Once you're comfortable with SF's approach, switch to auto mode:
```
/gsd auto
/sf auto
```
You can always press **Escape** to pause auto mode and return to step-by-step control.

8
gitbook/features/captures.md
View file

@ -7,11 +7,11 @@ Captures let you fire-and-forget thoughts during auto-mode execution. Instead of
While auto mode is running (or any time):
```
/gsd capture "add rate limiting to the API endpoints"
/gsd capture "the auth flow should support OAuth, not just JWT"
/sf capture "add rate limiting to the API endpoints"
/sf capture "the auth flow should support OAuth, not just JWT"
```
Captures are appended to `.gsd/CAPTURES.md` and triaged automatically between tasks.
Captures are appended to `.sf/CAPTURES.md` and triaged automatically between tasks.
## How It Works
@ -44,7 +44,7 @@ Plan-modifying resolutions (inject, replan) require your confirmation.
Trigger triage manually at any time:
```
/gsd triage
/sf triage
```
Useful when you've accumulated several captures and want to process them before the next natural seam.

8
gitbook/features/cost-management.md
View file

@ -4,9 +4,9 @@ SF tracks token usage and cost for every unit of work during auto mode. This dat
## Viewing Costs
**Dashboard:** Press `Ctrl+Alt+G` or type `/gsd status` for real-time cost breakdown.
**Dashboard:** Press `Ctrl+Alt+G` or type `/sf status` for real-time cost breakdown.
**Visualizer:** `/gsd visualize` → Metrics tab for detailed charts.
**Visualizer:** `/sf visualize` → Metrics tab for detailed charts.
**Aggregations:**
- By phase (research, planning, execution, completion, reassessment)
@ -66,9 +66,9 @@ This spreads your budget across remaining work instead of exhausting it early.
## Tips
- Start with `balanced` profile and a generous `budget_ceiling` to establish baseline costs
- Check `/gsd status` after a few slices to see per-slice cost averages
- Check `/sf status` after a few slices to see per-slice cost averages
- Switch to `budget` for well-understood, repetitive work
- Use `quality` only when architectural decisions are being made
- Use per-phase model selection to save: Opus for planning, Sonnet for execution
- Enable `dynamic_routing` for automatic model downgrading on simple tasks
- Use `/gsd visualize` → Metrics tab to see where your budget is going
- Use `/sf visualize` → Metrics tab to see where your budget is going

10
gitbook/features/dynamic-model-routing.md
View file

@ -75,14 +75,14 @@ The `budget` profile + dynamic routing provides maximum cost savings.
## Adaptive Learning
SF tracks routing outcomes in `.gsd/routing-history.json`. If a tier's failure rate exceeds 20% for a given task type, future classifications are bumped up.
SF tracks routing outcomes in `.sf/routing-history.json`. If a tier's failure rate exceeds 20% for a given task type, future classifications are bumped up.
Use `/gsd rate` to submit feedback:
Use `/sf rate` to submit feedback:
```
/gsd rate over # too powerful — use cheaper next time
/gsd rate ok # just right
/gsd rate under # too weak — use stronger next time
/sf rate over # too powerful — use cheaper next time
/sf rate ok # just right
/sf rate under # too weak — use stronger next time
```
Feedback is weighted 2x compared to automatic outcomes.

8
gitbook/features/github-sync.md
View file

@ -14,14 +14,14 @@ SF can auto-sync milestones, slices, and tasks to GitHub Issues, PRs, and Milest
github:
enabled: true
repo: "owner/repo" # auto-detected from git remote if omitted
labels: [gsd, auto-generated] # labels for created items
labels: [sf, auto-generated] # labels for created items
```
## Commands
| Command | Description |
|---------|-------------|
| `/github-sync bootstrap` | Initial setup — creates GitHub Milestones, Issues, and draft PRs from current `.gsd/` state |
| `/github-sync bootstrap` | Initial setup — creates GitHub Milestones, Issues, and draft PRs from current `.sf/` state |
| `/github-sync status` | Show sync mapping counts (milestones, slices, tasks) |
## How It Works
@ -31,7 +31,7 @@ SF can auto-sync milestones, slices, and tasks to GitHub Issues, PRs, and Milest
- Tasks → GitHub Issue checklists
- Completed slices → Draft PRs
Sync mapping is persisted in `.gsd/.github-sync.json`. The sync is rate-limit aware — it skips when the GitHub API rate limit is low.
Sync mapping is persisted in `.sf/.github-sync.json`. The sync is rate-limit aware — it skips when the GitHub API rate limit is low.
## Configuration
@ -39,6 +39,6 @@ Sync mapping is persisted in `.gsd/.github-sync.json`. The sync is rate-limit aw
github:
enabled: true
repo: "owner/repo"
labels: [gsd, auto-generated]
labels: [sf, auto-generated]
project: "Project ID" # optional: GitHub Project board
```

32
gitbook/features/headless.md
View file

@ -1,37 +1,37 @@
# Headless & CI Mode
`gsd headless` runs SF commands without a terminal UI — designed for CI pipelines, cron jobs, and scripted automation.
`sf headless` runs SF commands without a terminal UI — designed for CI pipelines, cron jobs, and scripted automation.
## Basic Usage
```bash
# Run auto mode
gsd headless
sf headless
# Run a single unit
gsd headless next
sf headless next
# With timeout for CI
gsd headless --timeout 600000 auto
sf headless --timeout 600000 auto
# Force a specific phase
gsd headless dispatch plan
sf headless dispatch plan
# Stream all events as JSONL
gsd headless --json auto
sf headless --json auto
```
## Creating Milestones Headlessly
```bash
# From a context file
gsd headless new-milestone --context brief.md --auto
sf headless new-milestone --context brief.md --auto
# From inline text
gsd headless new-milestone --context-text "Build a REST API with auth"
sf headless new-milestone --context-text "Build a REST API with auth"
# Pipe from stdin
echo "Build a CLI tool" | gsd headless new-milestone --context -
echo "Build a CLI tool" | sf headless new-milestone --context -
```
## CLI Flags
@ -56,27 +56,27 @@ echo "Build a CLI tool" | gsd headless new-milestone --context -
## Instant State Query
`gsd headless query` returns a JSON snapshot of project state — no AI session, instant response (~50ms):
`sf headless query` returns a JSON snapshot of project state — no AI session, instant response (~50ms):
```bash
gsd headless query | jq '.state.phase'
sf headless query | jq '.state.phase'
# "executing"
gsd headless query | jq '.next'
sf headless query | jq '.next'
# {"action":"dispatch","unitType":"execute-task","unitId":"M001/S01/T03"}
gsd headless query | jq '.cost.total'
sf headless query | jq '.cost.total'
# 4.25
```
Any `/gsd` subcommand works as a positional argument: `gsd headless status`, `gsd headless doctor`, etc.
Any `/sf` subcommand works as a positional argument: `sf headless status`, `sf headless doctor`, etc.
## MCP Server Mode
`gsd --mode mcp` runs SF as a Model Context Protocol server over stdin/stdout, exposing all SF tools to external AI clients:
`sf --mode mcp` runs SF as a Model Context Protocol server over stdin/stdout, exposing all SF tools to external AI clients:
```bash
gsd --mode mcp
sf --mode mcp
```
Compatible with Claude Desktop, VS Code Copilot, and any MCP host.

34
gitbook/features/parallel.md
View file

@ -3,7 +3,7 @@
Run multiple milestones simultaneously in isolated git worktrees. Each milestone gets its own worker process, branch, and context window.
{% hint style="info" %}
Parallel mode is off by default. Enable it in preferences to use `/gsd parallel` commands.
Parallel mode is off by default. Enable it in preferences to use `/sf parallel` commands.
{% endhint %}
## Quick Start
@ -17,18 +17,18 @@ Parallel mode is off by default. Enable it in preferences to use `/gsd parallel`
2. Start parallel execution:
```
/gsd parallel start
/sf parallel start
```
SF scans milestones, checks dependencies and file overlap, shows an eligibility report, and spawns workers.
3. Monitor:
```
/gsd parallel status
/sf parallel status
```
4. Stop:
```
/gsd parallel stop
/sf parallel stop
```
## How It Works
@ -43,7 +43,7 @@ Each worker is a separate SF process with complete isolation:
| Metrics | Own `metrics.json` |
| Crash recovery | Own `auto.lock` |
Workers communicate with the coordinator through file-based IPC — heartbeat files and signal files in `.gsd/parallel/`.
Workers communicate with the coordinator through file-based IPC — heartbeat files and signal files in `.sf/parallel/`.
## Eligibility
@ -68,19 +68,19 @@ parallel:
| Command | Description |
|---------|-------------|
| `/gsd parallel start` | Analyze and start workers |
| `/gsd parallel status` | Show all workers with progress and cost |
| `/gsd parallel stop [MID]` | Stop all or a specific worker |
| `/gsd parallel pause [MID]` | Pause all or a specific worker |
| `/gsd parallel resume [MID]` | Resume paused workers |
| `/gsd parallel merge [MID]` | Merge completed milestones to main |
| `/sf parallel start` | Analyze and start workers |
| `/sf parallel status` | Show all workers with progress and cost |
| `/sf parallel stop [MID]` | Stop all or a specific worker |
| `/sf parallel pause [MID]` | Pause all or a specific worker |
| `/sf parallel resume [MID]` | Resume paused workers |
| `/sf parallel merge [MID]` | Merge completed milestones to main |
## Merge Reconciliation
When milestones complete, their changes merge back to main:
- `.gsd/` state files are auto-resolved
- Code conflicts halt the merge — resolve manually and retry with `/gsd parallel merge <MID>`
- `.sf/` state files are auto-resolved
- Code conflicts halt the merge — resolve manually and retry with `/sf parallel merge <MID>`
## Budget Management
@ -91,7 +91,7 @@ When `budget_ceiling` is set, aggregate cost across all workers is tracked. When
| Problem | Fix |
|---------|-----|
| "Parallel mode is not enabled" | Set `parallel.enabled: true` |
| "No eligible milestones" | All milestones are complete or blocked; check `/gsd queue` |
| Worker crashed | Run `/gsd doctor --fix`, then `/gsd parallel start` |
| Merge conflicts | Resolve in `.gsd/worktrees/<MID>/`, then `/gsd parallel merge <MID>` |
| Workers seem stuck | Check if budget ceiling was reached via `/gsd parallel status` |
| "No eligible milestones" | All milestones are complete or blocked; check `/sf queue` |
| Worker crashed | Run `/sf doctor --fix`, then `/sf parallel start` |
| Merge conflicts | Resolve in `.sf/worktrees/<MID>/`, then `/sf parallel merge <MID>` |
| Workers seem stuck | Check if budget ceiling was reached via `/sf parallel status` |

18
gitbook/features/remote-questions.md
View file

@ -7,7 +7,7 @@ Remote questions let SF ask for your input via Slack, Discord, or Telegram when
### Discord
```
/gsd remote discord
/sf remote discord
```
The wizard prompts for your bot token, validates it, lets you pick a server and channel, sends a test message, and saves the config.
@ -20,7 +20,7 @@ The wizard prompts for your bot token, validates it, lets you pick a server and
### Slack
```
/gsd remote slack
/sf remote slack
```
**Bot requirements:**
@ -31,7 +31,7 @@ The wizard prompts for your bot token, validates it, lets you pick a server and
### Telegram
```
/gsd remote telegram
/sf remote telegram
```
**Bot requirements:**
@ -74,12 +74,12 @@ If no response arrives within `timeout_minutes`, SF continues with a timeout res
| Command | Description |
|---------|-------------|
| `/gsd remote` | Show menu and current status |
| `/gsd remote slack` | Set up Slack |
| `/gsd remote discord` | Set up Discord |
| `/gsd remote telegram` | Set up Telegram |
| `/gsd remote status` | Show current config |
| `/gsd remote disconnect` | Remove configuration |
| `/sf remote` | Show menu and current status |
| `/sf remote slack` | Set up Slack |
| `/sf remote discord` | Set up Discord |
| `/sf remote telegram` | Set up Telegram |
| `/sf remote status` | Show current config |
| `/sf remote disconnect` | Remove configuration |
## Troubleshooting

10
gitbook/features/skills.md
View file

@ -36,7 +36,7 @@ npx skills update
## Onboarding Catalog
During `gsd init`, SF detects your project's tech stack and recommends relevant skill packs:
During `sf init`, SF detects your project's tech stack and recommends relevant skill packs:
- **Swift** — SwiftUI, Swift Core, concurrency, Charts, Testing
- **iOS** — App Intents, Widgets, StoreKit, MapKit, Core ML, Vision, accessibility
@ -100,10 +100,10 @@ Project-local skills can be committed to git so team members share the same skil
Track skill performance:
```
/gsd skill-health # overview table
/gsd skill-health rust-core # detailed view for one skill
/gsd skill-health --stale 30 # skills unused for 30+ days
/gsd skill-health --declining # skills with falling success rates
/sf skill-health # overview table
/sf skill-health rust-core # detailed view for one skill
/sf skill-health --stale 30 # skills unused for 30+ days
/sf skill-health --declining # skills with falling success rates
```
The dashboard flags:

38
gitbook/features/teams.md
View file

@ -7,7 +7,7 @@ SF supports multi-user workflows where several developers work on the same repos
The simplest way: set team mode in your project preferences.
```yaml
# .gsd/PREFERENCES.md (committed to git)
# .sf/PREFERENCES.md (committed to git)
---
version: 1
mode: team
@ -32,23 +32,23 @@ Share planning artifacts while keeping runtime files local:
```bash
# Runtime files (per-developer, gitignore these)
.gsd/auto.lock
.gsd/completed-units.json
.gsd/STATE.md
.gsd/metrics.json
.gsd/activity/
.gsd/runtime/
.gsd/worktrees/
.gsd/milestones/**/continue.md
.gsd/milestones/**/*-CONTINUE.md
.sf/auto.lock
.sf/completed-units.json
.sf/STATE.md
.sf/metrics.json
.sf/activity/
.sf/runtime/
.sf/worktrees/
.sf/milestones/**/continue.md
.sf/milestones/**/*-CONTINUE.md
```
**What gets shared** (committed to git):
- `.gsd/PREFERENCES.md` — project preferences
- `.gsd/PROJECT.md` — living project description
- `.gsd/REQUIREMENTS.md` — requirement contract
- `.gsd/DECISIONS.md` — architectural decisions
- `.gsd/milestones/` — roadmaps, plans, summaries, research
- `.sf/PREFERENCES.md` — project preferences
- `.sf/PROJECT.md` — living project description
- `.sf/REQUIREMENTS.md` — requirement contract
- `.sf/DECISIONS.md` — architectural decisions
- `.sf/milestones/` — roadmaps, plans, summaries, research
**What stays local** (gitignored):
- Lock files, metrics, state, activity logs, worktrees
@ -56,11 +56,11 @@ Share planning artifacts while keeping runtime files local:
## Commit the Config
```bash
git add .gsd/PREFERENCES.md
git add .sf/PREFERENCES.md
git commit -m "chore: enable SF team workflow"
```
## Keeping `.gsd/` Local
## Keeping `.sf/` Local
For teams where only some members use SF:
@ -69,13 +69,13 @@ git:
commit_docs: false
```
This gitignores `.gsd/` entirely. You get structured planning without affecting teammates.
This gitignores `.sf/` entirely. You get structured planning without affecting teammates.
## Parallel Development
Multiple developers can run auto mode simultaneously on different milestones. Each developer:
- Gets their own worktree (`.gsd/worktrees/<MID>/`)
- Gets their own worktree (`.sf/worktrees/<MID>/`)
- Works on a unique `milestone/<MID>` branch
- Squash-merges to main independently

6
gitbook/features/token-optimization.md
View file

@ -91,9 +91,9 @@ SF tracks success and failure of tier assignments over time. If a model tier's f
Submit manual feedback with:
```
/gsd rate over # model was overpowered — use cheaper next time
/gsd rate ok # model was appropriate
/gsd rate under # model was too weak — use stronger next time
/sf rate over # model was overpowered — use cheaper next time
/sf rate ok # model was appropriate
/sf rate under # model was too weak — use stronger next time
```
## Observation Masking

8
gitbook/features/visualizer.md
View file

@ -5,7 +5,7 @@ The workflow visualizer is a full-screen terminal overlay showing project progre
## Opening
```
/gsd visualize
/sf visualize
```
Or configure automatic display after milestone completion:
@ -71,11 +71,11 @@ The visualizer auto-refreshes every 2 seconds, staying current alongside running
For shareable reports outside the terminal:
```
/gsd export --html # current milestone
/gsd export --html --all # all milestones
/sf export --html # current milestone
/sf export --html --all # all milestones
```
Generates self-contained HTML files in `.gsd/reports/` with progress tree, dependency graph, cost charts, timeline, and changelog. All CSS and JS are inlined — no external dependencies. Printable to PDF from any browser.
Generates self-contained HTML files in `.sf/reports/` with progress tree, dependency graph, cost charts, timeline, and changelog. All CSS and JS are inlined — no external dependencies. Printable to PDF from any browser.
```yaml
auto_report: true # auto-generate after milestone completion (default)

Some files were not shown because too many files have changed in this diff Show more