Merge pull request #674 from trek-e/chore/docs-v2.20.0
docs: update documentation for v2.20.0 release
This commit is contained in:
TÂCHES
GitHub
commit
feccaf2998
5 changed files with 88 additions and 3 deletions
|
|
@ -355,8 +355,17 @@ unique_milestone_ids: true
|
|||
| `uat_dispatch` | Enable automatic UAT runs after slice completion |
|
||||
| `always_use_skills` | Skills to always load when relevant |
|
||||
| `skill_rules` | Situational rules for skill routing |
|
||||
| `skill_staleness_days` | Skills unused for N days get deprioritized (default: 60, 0 = disabled) |
|
||||
| `unique_milestone_ids` | Uses unique milestone names to avoid clashes when working in teams of people |
|
||||
|
||||
### Agent Instructions
|
||||
|
||||
Create an `agent-instructions.md` file in your project root to inject persistent per-project behavioral guidance into every agent session. This file is loaded automatically and provides project-specific context the LLM should always have — coding standards, architectural decisions, domain terminology, or workflow preferences.
|
||||
|
||||
### Debug Mode
|
||||
|
||||
Start GSD with `gsd --debug` to enable structured JSONL diagnostic logging. Debug logs capture dispatch decisions, state transitions, and timing data for troubleshooting auto-mode issues.
|
||||
|
||||
### Token Optimization (v2.17)
|
||||
|
||||
GSD 2.17 introduced a coordinated token optimization system that reduces usage by 40-60% on cost-sensitive workloads. Set a single preference to coordinate model selection, phase skipping, and context compression:
|
||||
|
|
|
|||
|
|
@ -7,6 +7,7 @@
|
|||
| `/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 GSD guarantees (atomic commits, state tracking) without full 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) |
|
||||
|
|
@ -16,9 +17,22 @@
|
|||
| `/gsd triage` | Manually trigger triage of pending captures |
|
||||
| `/gsd visualize` | Open workflow visualizer (progress, deps, metrics, timeline) |
|
||||
| `/gsd knowledge` | Add persistent project knowledge (rule, pattern, or lesson) |
|
||||
| `/gsd help` | Categorized command reference with descriptions for all GSD 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 doctor` | Runtime health checks (7 checks) with auto-fix for common state corruption issues |
|
||||
| `/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 |
|
||||
| `/gsd doctor` | Validate `.gsd/` integrity, find and fix issues |
|
||||
|
||||
## Git Commands
|
||||
|
||||
|
|
@ -55,4 +69,5 @@
|
|||
|------|-------------|
|
||||
| `gsd` | Start a new interactive session |
|
||||
| `gsd --continue` (`-c`) | Resume the most recent session for the current directory |
|
||||
| `gsd --debug` | Enable structured JSONL diagnostic logging for troubleshooting dispatch and state issues |
|
||||
| `gsd config` | Re-run the setup wizard (LLM provider + tool keys) |
|
||||
|
|
|
|||
|
|
@ -434,6 +434,7 @@ git:
|
|||
|
||||
# Skills
|
||||
skill_discovery: suggest
|
||||
skill_staleness_days: 60 # Skills unused for N days get deprioritized (0 = disabled)
|
||||
always_use_skills:
|
||||
- debug-like-expert
|
||||
skill_rules:
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# Remote Questions
|
||||
|
||||
Remote questions allow GSD to ask for user input via Slack or Discord when running in headless auto-mode. When GSD encounters a decision point that needs human input, it posts the question to your configured channel and polls for a response.
|
||||
Remote questions allow GSD to ask for user input via Slack, Discord, or Telegram when running in headless auto-mode. When GSD encounters a decision point that needs human input, it posts the question to your configured channel and polls for a response.
|
||||
|
||||
## Setup
|
||||
|
||||
|
|
@ -45,13 +45,31 @@ The setup wizard:
|
|||
- Bot must be invited to the target channel
|
||||
- Typical scopes for public/private channels: `chat:write`, `reactions:read`, `reactions:write`, `channels:read`, `groups:read`, `channels:history`, `groups:history`
|
||||
|
||||
### Telegram
|
||||
|
||||
```
|
||||
/gsd remote telegram
|
||||
```
|
||||
|
||||
The setup wizard:
|
||||
1. Prompts for your Telegram bot token (from [@BotFather](https://t.me/BotFather))
|
||||
2. Validates the token against the Telegram API
|
||||
3. Prompts for the chat ID (group or private chat)
|
||||
4. Sends a test message to confirm permissions
|
||||
5. Saves the configuration
|
||||
|
||||
**Bot requirements:**
|
||||
- A Telegram bot token from [@BotFather](https://t.me/BotFather)
|
||||
- Bot must be added to the target group chat (or use private chat with the bot)
|
||||
- The `TELEGRAM_BOT_TOKEN` environment variable must be set
|
||||
|
||||
## Configuration
|
||||
|
||||
Remote questions are configured in `~/.gsd/preferences.md`:
|
||||
|
||||
```yaml
|
||||
remote_questions:
|
||||
channel: discord # or slack
|
||||
channel: discord # or slack or telegram
|
||||
channel_id: "1234567890123456789"
|
||||
timeout_minutes: 5 # 1-30, default 5
|
||||
poll_interval_seconds: 5 # 2-30, default 5
|
||||
|
|
|
|||
|
|
@ -82,3 +82,45 @@ Place skills in your project for project-specific guidance:
|
|||
.pi/agent/skills/my-project-skill/
|
||||
SKILL.md
|
||||
```
|
||||
|
||||
## Skill Lifecycle Management
|
||||
|
||||
GSD tracks skill performance across auto-mode sessions and surfaces health data to help you maintain skill quality.
|
||||
|
||||
### Skill Telemetry
|
||||
|
||||
Every auto-mode unit records which skills were available and actively loaded. This data is stored in `metrics.json` alongside existing token and cost tracking.
|
||||
|
||||
### Skill Health Dashboard
|
||||
|
||||
View skill performance with `/gsd 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
|
||||
```
|
||||
|
||||
The dashboard flags skills that may need attention:
|
||||
- **Success rate below 70%** over the last 10 uses
|
||||
- **Token usage rising 20%+** compared to the previous window
|
||||
- **Stale skills** unused beyond the configured threshold
|
||||
|
||||
### Staleness Detection
|
||||
|
||||
Skills unused for a configurable number of days are flagged as stale and can be automatically deprioritized:
|
||||
|
||||
```yaml
|
||||
---
|
||||
skill_staleness_days: 60 # default: 60, set to 0 to disable
|
||||
---
|
||||
```
|
||||
|
||||
Stale skills are excluded from automatic matching but remain invokable explicitly via `read`.
|
||||
|
||||
### Heal-Skill (Post-Unit Analysis)
|
||||
|
||||
When configured as a post-unit hook, GSD 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.
|
||||
|
||||
Key design principle: skills are **never auto-modified**. Research shows curated skills outperform auto-generated ones significantly, so the human review step is critical.
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue