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
This commit is contained in:
Flux Labs
GitHub
parent
2924a1d666
commit
6998ef2ae4
2 changed files with 279 additions and 15 deletions
|
|
@ -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
|
||||
---
|
||||
```
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue