From 6998ef2ae4972b361ad070111242c0a4d56d5b2a Mon Sep 17 00:00:00 2001 From: Flux Labs Date: Mon, 16 Mar 2026 08:09:50 -0500 Subject: [PATCH] docs: comprehensive update to preferences reference and configuration guide (#614) Update both docs/configuration.md (user-facing) and src/resources/extensions/gsd/docs/preferences-reference.md (internal) with complete coverage of all GSD preferences: - Add /gsd prefs subcommands table (global, project, status, wizard, setup) - Document token_profile (budget/balanced/quality) and phases settings - Document context_pause_threshold field - Document remote_questions configuration (Slack/Discord) - Document git.merge_strategy (squash/merge) and git.isolation (worktree/branch) - Expand post_unit_hooks with missing agent field - Expand pre_dispatch_hooks with skip_if, unit_type, model fields and action validation rules - Add known unit types list for hook before/after arrays - Add examples for pre-dispatch hooks (modify/skip/replace) - Add examples for token profile, phases, and remote questions - Update models to show all 6 phases (research, planning, execution, execution_simple, completion, subagent) - Add full example combining all major settings --- docs/configuration.md | 181 ++++++++++++++++-- .../gsd/docs/preferences-reference.md | 113 ++++++++++- 2 files changed, 279 insertions(+), 15 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 8f1a034e4..8b74333d1 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -2,6 +2,17 @@ GSD preferences live in `~/.gsd/preferences.md` (global) or `.gsd/preferences.md` (project-local). Manage interactively with `/gsd prefs`. +## `/gsd 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 | + ## Preferences File Format Preferences use YAML frontmatter in a markdown file: @@ -60,6 +71,21 @@ models: - `execution_simple` — used for tasks classified as "simple" by the [complexity router](./token-optimization.md#complexity-based-task-routing) - `subagent` — model for delegated subagent tasks (scout, researcher, worker) - Provider targeting: use `provider/model` format (e.g., `bedrock/claude-sonnet-4-6`) or the `provider` field in object format +- Omit a key to use whatever model is currently active + +**With fallbacks:** + +```yaml +models: + planning: + model: claude-opus-4-6 + fallbacks: + - openrouter/z-ai/glm-5 + - openrouter/moonshotai/kimi-k2.5 + provider: bedrock # optional: target a specific provider +``` + +When a model fails to switch (provider unavailable, rate limited, credits exhausted), GSD automatically tries the next model in the `fallbacks` list. ### `token_profile` @@ -67,6 +93,12 @@ Coordinates model selection, phase skipping, and context compression. See [Token Values: `budget`, `balanced` (default), `quality` +| Profile | Behavior | +|---------|----------| +| `budget` | Skips research + reassessment phases, uses cheaper models | +| `balanced` | Default behavior — all phases run, standard model selection | +| `quality` | All phases run, prefers higher-quality models | + ### `phases` Fine-grained control over which phases run in auto mode: @@ -96,6 +128,7 @@ Timeout thresholds for auto mode supervision: ```yaml auto_supervisor: + model: claude-sonnet-4-6 # optional: model for supervisor (defaults to active model) soft_timeout_minutes: 20 # warn LLM to wrap up idle_timeout_minutes: 10 # detect stalls hard_timeout_minutes: 30 # pause auto mode @@ -103,7 +136,7 @@ auto_supervisor: ### `budget_ceiling` -USD ceiling. Auto mode pauses when reached. +Maximum USD to spend during auto mode. No `$` sign — just the number. ```yaml budget_ceiling: 50.00 @@ -119,6 +152,16 @@ How the budget ceiling is enforced: | `pause` | Pause auto mode (default when ceiling is set) | | `halt` | Stop auto mode entirely | +### `context_pause_threshold` + +Context window usage percentage (0-100) at which auto mode pauses for checkpointing. Set to `0` to disable. + +```yaml +context_pause_threshold: 80 # pause at 80% context usage +``` + +Default: `0` (disabled) + ### `uat_dispatch` Enable automatic UAT (User Acceptance Test) runs after slice completion: @@ -149,12 +192,27 @@ git: pre_merge_check: false # run checks before worktree merge (true/false/"auto") commit_type: feat # override conventional commit prefix main_branch: main # primary branch name + merge_strategy: squash # how worktree branches merge: "squash" or "merge" + isolation: worktree # git isolation: "worktree" or "branch" commit_docs: true # commit .gsd/ artifacts to git (set false to keep local) ``` +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `auto_push` | boolean | `false` | Push commits to remote after committing | +| `push_branches` | boolean | `false` | Push milestone branch to remote | +| `remote` | string | `"origin"` | Git remote name | +| `snapshots` | boolean | `false` | WIP snapshot commits during long tasks | +| `pre_merge_check` | bool/string | `false` | Run checks before merge (`true`/`false`/`"auto"`) | +| `commit_type` | string | (inferred) | Override conventional commit prefix (`feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `perf`, `ci`, `build`, `style`) | +| `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) or `"branch"` (work in project root — useful for submodule-heavy repos) | +| `commit_docs` | boolean | `true` | Commit `.gsd/` planning artifacts to git. Set `false` to keep local-only | + ### `notifications` -Control what notifications GSD sends (for remote question integrations): +Control what notifications GSD sends during auto mode: ```yaml notifications: @@ -168,14 +226,14 @@ notifications: ### `remote_questions` -Route interactive questions to Slack or Discord for headless auto-mode: +Route interactive questions to Slack or Discord for headless auto mode: ```yaml remote_questions: channel: slack # or discord channel_id: "C1234567890" - timeout_minutes: 15 - poll_interval_seconds: 10 + timeout_minutes: 15 # question timeout (1-30 minutes) + poll_interval_seconds: 10 # poll interval (2-30 seconds) ``` ### `post_unit_hooks` @@ -187,22 +245,57 @@ post_unit_hooks: - name: code-review after: [execute-task] prompt: "Review the code changes for quality and security issues." - model: claude-opus-4-6 - max_cycles: 1 + model: claude-opus-4-6 # optional: model override + max_cycles: 1 # max fires per trigger (1-10, default: 1) + artifact: REVIEW.md # optional: skip if this file exists + retry_on: NEEDS-REWORK.md # optional: re-run trigger unit if this file appears + agent: review-agent # optional: agent definition to use + enabled: true # optional: disable without removing ``` +**Known unit types for `after`:** `research-milestone`, `plan-milestone`, `research-slice`, `plan-slice`, `execute-task`, `complete-slice`, `replan-slice`, `reassess-roadmap`, `run-uat` + +**Prompt substitutions:** `{milestoneId}`, `{sliceId}`, `{taskId}` are replaced with current context values. + ### `pre_dispatch_hooks` -Hooks that intercept units before dispatch: +Hooks that intercept units before dispatch. Three actions available: + +**Modify** — prepend/append text to the unit prompt: ```yaml pre_dispatch_hooks: - - name: add-context + - name: add-standards before: [execute-task] action: modify - prepend: "Remember to follow our coding standards document." + prepend: "Follow our coding standards document." + append: "Run linting after changes." ``` +**Skip** — skip the unit entirely: + +```yaml +pre_dispatch_hooks: + - name: skip-research + before: [research-slice] + action: skip + skip_if: RESEARCH.md # optional: only skip if this file exists +``` + +**Replace** — replace the unit prompt entirely: + +```yaml +pre_dispatch_hooks: + - name: custom-execute + before: [execute-task] + action: replace + prompt: "Execute the task using TDD methodology." + unit_type: execute-task-tdd # optional: override unit type label + model: claude-opus-4-6 # optional: model override +``` + +All pre-dispatch hooks support `enabled: true/false` to toggle without removing. + ### `always_use_skills` / `prefer_skills` / `avoid_skills` Skill routing preferences: @@ -215,9 +308,11 @@ prefer_skills: avoid_skills: [] ``` +Skills can be bare names (looked up in `~/.gsd/agent/skills/`) or absolute paths. + ### `skill_rules` -Situational skill routing: +Situational skill routing with human-readable triggers: ```yaml skill_rules: @@ -225,6 +320,8 @@ skill_rules: use: [clerk] - when: frontend styling work prefer: [frontend-design] + - when: working with legacy code + avoid: [aggressive-refactor] ``` ### `custom_instructions` @@ -236,3 +333,65 @@ custom_instructions: - "Always use TypeScript strict mode" - "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. + +## Full Example + +```yaml +--- +version: 1 + +# Model selection +models: + research: openrouter/deepseek/deepseek-r1 + planning: + model: claude-opus-4-6 + fallbacks: + - openrouter/z-ai/glm-5 + execution: claude-sonnet-4-6 + execution_simple: claude-haiku-4-5-20250414 + completion: claude-sonnet-4-6 + +# Token optimization +token_profile: balanced + +# Budget +budget_ceiling: 25.00 +budget_enforcement: pause +context_pause_threshold: 80 + +# Supervision +auto_supervisor: + soft_timeout_minutes: 15 + hard_timeout_minutes: 25 + +# Git +git: + auto_push: true + merge_strategy: squash + isolation: worktree + commit_docs: true + +# Skills +skill_discovery: suggest +always_use_skills: + - debug-like-expert +skill_rules: + - when: task involves authentication + use: [clerk] + +# Notifications +notifications: + on_complete: false + on_milestone: true + on_attention: true + +# Hooks +post_unit_hooks: + - name: code-review + after: [execute-task] + prompt: "Review {sliceId}/{taskId} for quality and security." + artifact: REVIEW.md +--- +``` diff --git a/src/resources/extensions/gsd/docs/preferences-reference.md b/src/resources/extensions/gsd/docs/preferences-reference.md index 8a0b4fd72..9033bcb0f 100644 --- a/src/resources/extensions/gsd/docs/preferences-reference.md +++ b/src/resources/extensions/gsd/docs/preferences-reference.md @@ -82,7 +82,7 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea - `custom_instructions`: extra durable instructions related to skill use. For operational project knowledge (recurring rules, gotchas, patterns), use `.gsd/KNOWLEDGE.md` instead — it's injected into every agent prompt automatically and agents can append to it during execution. -- `models`: per-stage model selection for auto-mode. Keys: `research`, `planning`, `execution`, `completion`. Values can be: +- `models`: per-stage model selection for auto-mode. Keys: `research`, `planning`, `execution`, `execution_simple`, `completion`, `subagent`. Values can be: - Simple string: `"claude-sonnet-4-6"` — single model, no fallbacks - Provider-qualified string: `"bedrock/claude-sonnet-4-6"` — targets a specific provider when the same model ID exists across multiple providers - Object with fallbacks: `{ model: "claude-opus-4-6", fallbacks: ["glm-5", "minimax-m2.5"] }` — tries fallbacks in order if primary fails @@ -124,6 +124,19 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea - `context_pause_threshold`: number (0-100) — context window usage percentage at which auto-mode should pause to suggest checkpointing. Set to `0` to disable. Default: `0` (disabled). +- `token_profile`: `"budget"`, `"balanced"`, or `"quality"` — coordinates model selection, phase skipping, and context compression. `budget` skips research/reassessment and uses cheaper models; `balanced` (default) runs all phases; `quality` prefers higher-quality models. See token-optimization docs. + +- `phases`: fine-grained control over which phases run. Usually set by `token_profile`, but can be overridden. Keys: + - `skip_research`: boolean — skip milestone-level research. Default: `false`. + - `skip_reassess`: boolean — skip roadmap reassessment after each slice. Default: `false`. + - `skip_slice_research`: boolean — skip per-slice research. Default: `false`. + +- `remote_questions`: route interactive questions to Slack/Discord for headless auto-mode. Keys: + - `channel`: `"slack"` or `"discord"` — channel type. + - `channel_id`: string or number — channel ID. + - `timeout_minutes`: number — question timeout in minutes (clamped 1-30). + - `poll_interval_seconds`: number — poll interval in seconds (clamped 2-30). + - `notifications`: configures desktop notification behavior during auto-mode. Keys: - `enabled`: boolean — master toggle for all notifications. Default: `true`. - `on_complete`: boolean — notify when a unit completes. Default: `true`. @@ -140,8 +153,9 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea - `prompt`: string — prompt sent to the LLM. Supports `{milestoneId}`, `{sliceId}`, `{taskId}` substitutions. - `max_cycles`: number — max times this hook fires per trigger (default: 1, max: 10). - `model`: string — optional model override. - - `artifact`: string — expected output file (skip if exists). - - `retry_on`: string — file that triggers re-run of the trigger unit. + - `artifact`: string — expected output file name (relative to task/slice dir). Hook is skipped if file already exists (idempotent). + - `retry_on`: string — if this file is produced instead of the artifact, re-run the trigger unit then re-run hooks. + - `agent`: string — agent definition file to use for hook execution. - `enabled`: boolean — toggle without removing (default: `true`). - `pre_dispatch_hooks`: array — hooks that fire before a unit is dispatched. Each entry has: @@ -150,9 +164,19 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea - `action`: `"modify"`, `"skip"`, or `"replace"` — what to do with the unit. - `prepend`: string — text prepended to unit prompt (for `"modify"` action). - `append`: string — text appended to unit prompt (for `"modify"` action). - - `prompt`: string — replacement prompt (for `"replace"` action). + - `prompt`: string — replacement prompt (for `"replace"` action; required when action is `"replace"`). + - `unit_type`: string — override unit type label (for `"replace"` action). + - `skip_if`: string — for `"skip"` action: only skip if this file exists (relative to unit dir). + - `model`: string — optional model override when this hook fires. - `enabled`: boolean — toggle without removing (default: `true`). + **Action validation:** + - `"modify"` requires at least one of `prepend` or `append`. + - `"replace"` requires `prompt`. + - `"skip"` is valid with no additional fields. + + **Known unit types for `before`/`after`:** `research-milestone`, `plan-milestone`, `research-slice`, `plan-slice`, `execute-task`, `complete-slice`, `replan-slice`, `reassess-roadmap`, `run-uat`. + --- ## Best Practices @@ -371,3 +395,84 @@ post_unit_hooks: ``` Runs an automated code review after each task execution. Skips if `REVIEW.md` already exists (idempotent). + +--- + +## Pre-Dispatch Hooks Examples + +**Modify — inject instructions before every task:** + +```yaml +--- +version: 1 +pre_dispatch_hooks: + - name: enforce-standards + before: + - execute-task + action: modify + prepend: "Follow our TypeScript coding standards and always run linting." +--- +``` + +**Skip — skip per-slice research when a research file already exists:** + +```yaml +--- +version: 1 +pre_dispatch_hooks: + - name: skip-existing-research + before: + - research-slice + action: skip + skip_if: RESEARCH.md +--- +``` + +**Replace — substitute a custom prompt for task execution:** + +```yaml +--- +version: 1 +pre_dispatch_hooks: + - name: tdd-execute + before: + - execute-task + action: replace + prompt: "Implement the task using strict TDD. Write failing tests first, then implement, then refactor." + model: claude-opus-4-6 +--- +``` + +--- + +## Token Profile & Phases Example + +```yaml +--- +version: 1 +token_profile: budget +phases: + skip_research: true + skip_reassess: true + skip_slice_research: false +--- +``` + +Uses the `budget` profile to minimize token usage, with explicit override to keep slice-level research enabled. + +--- + +## Remote Questions Example + +```yaml +--- +version: 1 +remote_questions: + channel: slack + channel_id: "C0123456789" + timeout_minutes: 15 + poll_interval_seconds: 10 +--- +``` + +Routes interactive questions to a Slack channel for headless auto-mode sessions. Questions time out after 15 minutes if unanswered.