diff --git a/README.md b/README.md index 528ce698a..a42952541 100644 --- a/README.md +++ b/README.md @@ -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: diff --git a/docs/commands.md b/docs/commands.md index a026e5803..c38c65f5f 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -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 ` | 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) | diff --git a/docs/configuration.md b/docs/configuration.md index 5bcd62d4a..49beeb7f2 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -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: diff --git a/docs/remote-questions.md b/docs/remote-questions.md index ea84bbd70..8e4ce3555 100644 --- a/docs/remote-questions.md +++ b/docs/remote-questions.md @@ -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 diff --git a/docs/skills.md b/docs/skills.md index af1001ddb..213b19579 100644 --- a/docs/skills.md +++ b/docs/skills.md @@ -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.