From 8aa8e6c494ce9e08ebf89e6325fa54aa8b51d717 Mon Sep 17 00:00:00 2001 From: Lex Christopherson Date: Tue, 17 Mar 2026 15:35:55 -0600 Subject: [PATCH] docs: document all preferences.md fields in reference and template Add 9 missing fields to preferences-reference.md: skill_staleness_days, git.manage_gitignore, dynamic_routing, auto_visualize, auto_report, parallel, verification_commands, verification_auto_fix, and verification_max_retries. Add examples for dynamic routing, parallel execution, and verification. Update the preferences template to include all fields from the schema. Co-Authored-By: Claude Opus 4.6 (1M context) --- .../gsd/docs/preferences-reference.md | 83 +++++++++++++++++++ .../extensions/gsd/templates/preferences.md | 34 ++++++++ 2 files changed, 117 insertions(+) diff --git a/src/resources/extensions/gsd/docs/preferences-reference.md b/src/resources/extensions/gsd/docs/preferences-reference.md index 342e0cf63..578e803a6 100644 --- a/src/resources/extensions/gsd/docs/preferences-reference.md +++ b/src/resources/extensions/gsd/docs/preferences-reference.md @@ -104,6 +104,8 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea - Object with provider: `{ model: "claude-opus-4-6", provider: "bedrock" }` — explicit provider targeting in object format - Omit a key to use whatever model is currently active. Fallbacks are tried when model switching fails (provider unavailable, rate limited, etc.). +- `skill_staleness_days`: number — skills unused for this many days get deprioritized during discovery. Set to `0` to disable staleness tracking. Default: `60`. + - `skill_discovery`: controls how GSD discovers and applies skills during auto-mode. Valid values: - `auto` — skills are found and applied automatically without prompting. - `suggest` — (default) skills are identified during research but not installed automatically. @@ -126,6 +128,7 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea - `merge_strategy`: `"squash"` or `"merge"` — controls how worktree branches are merged back. `"squash"` combines all commits into one; `"merge"` preserves individual commits. Default: `"squash"`. - `isolation`: `"worktree"`, `"branch"`, or `"none"` — controls auto-mode git isolation strategy. `"worktree"` creates a milestone worktree for isolated work; `"branch"` works directly in the project root but creates a milestone branch (useful for submodule-heavy repos); `"none"` works directly on the current branch with no worktree or milestone branch (ideal for step-mode with hot reloads). Default: `"worktree"`. - `commit_docs`: boolean — when `false`, prevents GSD from committing `.gsd/` planning artifacts to git. The `.gsd/` folder is added to `.gitignore` and kept local-only. Useful for teams where only some members use GSD, or when company policy requires a clean repository. Default: `true`. + - `manage_gitignore`: boolean — when `false`, GSD will not touch `.gitignore` at all. Useful when your project has a strictly managed `.gitignore` and you don't want GSD adding entries. Default: `true`. - `worktree_post_create`: string — script to run after a worktree is created (both auto-mode and manual `/worktree`). Receives `SOURCE_DIR` and `WORKTREE_DIR` as environment variables. Can be absolute or relative to project root. Runs with 30-second timeout. Failure is non-fatal (logged as warning). Default: none. - `unique_milestone_ids`: boolean — when `true`, generates milestone IDs in `M{seq}-{rand6}` format (e.g. `M001-eh88as`) instead of plain sequential `M001`. Prevents ID collisions in team workflows where multiple contributors create milestones concurrently. Both formats coexist — existing `M001`-style milestones remain valid. Default: `false`. @@ -161,6 +164,31 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea - `on_milestone`: boolean — notify when a milestone finishes. Default: `true`. - `on_attention`: boolean — notify when manual attention is needed. Default: `true`. +- `dynamic_routing`: configures the dynamic model router that adjusts model selection based on task complexity. Keys: + - `enabled`: boolean — enable dynamic routing. Default: `false`. + - `tier_models`: object — model overrides per complexity tier. Keys: `light`, `standard`, `heavy`. Values are model ID strings. + - `escalate_on_failure`: boolean — escalate to a higher-tier model when the current one fails. Default: `true`. + - `budget_pressure`: boolean — downgrade model tier when budget is under pressure. Default: `true`. + - `cross_provider`: boolean — allow routing across different providers. Default: `true`. + - `hooks`: boolean — enable routing hooks. Default: `true`. + +- `auto_visualize`: boolean — show a visualizer hint after each milestone completion in auto-mode. Default: `false`. + +- `auto_report`: boolean — generate an HTML report snapshot after each milestone completion. Default: `true`. + +- `parallel`: configures parallel orchestration for running multiple slices concurrently. Keys: + - `enabled`: boolean — enable parallel execution. Default: `false`. + - `max_workers`: number — maximum concurrent workers (1-4). Default: `2`. + - `budget_ceiling`: number — optional per-parallel-run budget ceiling. + - `merge_strategy`: `"per-slice"` or `"per-milestone"` — when to merge worktree results back. Default: `"per-milestone"`. + - `auto_merge`: `"auto"`, `"confirm"`, or `"manual"` — merge behavior after completion. `"auto"` merges immediately; `"confirm"` asks first; `"manual"` leaves branches for you. Default: `"confirm"`. + +- `verification_commands`: string[] — shell commands to run as verification after task execution (e.g., `["npm test", "npm run lint"]`). Commands run in order; if any fails, the task is marked as needing fixes. + +- `verification_auto_fix`: boolean — when `true`, automatically attempt to fix verification failures instead of just reporting them. Default: `false`. + +- `verification_max_retries`: number — maximum number of fix-and-retry cycles for verification failures. Default: `0` (no retries). + - `uat_dispatch`: boolean — when `true`, enables UAT (User Acceptance Testing) dispatch mode. Default: `false`. - `post_unit_hooks`: array — hooks that fire after a unit completes. Each entry has: @@ -531,3 +559,58 @@ remote_questions: ``` Routes interactive questions to a Slack channel for headless auto-mode sessions. Questions time out after 15 minutes if unanswered. + +--- + +## Dynamic Routing Example + +```yaml +--- +version: 1 +dynamic_routing: + enabled: true + tier_models: + light: openrouter/minimax/minimax-m2.5 + standard: claude-sonnet-4-6 + heavy: claude-opus-4-6 + escalate_on_failure: true + budget_pressure: true +--- +``` + +Automatically selects model tier based on task complexity. Simple tasks use the `light` model, complex tasks escalate to `heavy`. Under budget pressure, tasks are routed to cheaper tiers. + +--- + +## Parallel Execution Example + +```yaml +--- +version: 1 +parallel: + enabled: true + max_workers: 3 + merge_strategy: per-milestone + auto_merge: confirm +--- +``` + +Runs up to 3 slices concurrently in separate worktrees. Results are merged per-milestone with user confirmation. + +--- + +## Verification Example + +```yaml +--- +version: 1 +verification_commands: + - npm test + - npm run lint + - npm run typecheck +verification_auto_fix: true +verification_max_retries: 2 +--- +``` + +Runs test, lint, and typecheck after each task. On failure, auto-fix is attempted up to 2 times before reporting the issue. diff --git a/src/resources/extensions/gsd/templates/preferences.md b/src/resources/extensions/gsd/templates/preferences.md index 6f0d041e5..54df573b4 100644 --- a/src/resources/extensions/gsd/templates/preferences.md +++ b/src/resources/extensions/gsd/templates/preferences.md @@ -8,6 +8,7 @@ skill_rules: [] custom_instructions: [] models: {} skill_discovery: +skill_staleness_days: auto_supervisor: {} git: auto_push: @@ -19,10 +20,36 @@ git: main_branch: merge_strategy: isolation: + commit_docs: + manage_gitignore: + worktree_post_create: unique_milestone_ids: budget_ceiling: budget_enforcement: context_pause_threshold: +token_profile: +phases: + skip_research: + skip_reassess: + skip_slice_research: +dynamic_routing: + enabled: + tier_models: {} + escalate_on_failure: + budget_pressure: + cross_provider: + hooks: +auto_visualize: +auto_report: +parallel: + enabled: + max_workers: + budget_ceiling: + merge_strategy: + auto_merge: +verification_commands: [] +verification_auto_fix: +verification_max_retries: notifications: enabled: on_complete: @@ -30,7 +57,14 @@ notifications: on_budget: on_milestone: on_attention: +remote_questions: + channel: + channel_id: + timeout_minutes: + poll_interval_seconds: uat_dispatch: +post_unit_hooks: [] +pre_dispatch_hooks: [] --- # GSD Skill Preferences