golem15/msd-core
3
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs: update README and docs/ for v1.27 release

Browse Source 
Add documentation for all new v1.27 features:
- 7 new commands (/gsd:fast, /gsd:review, /gsd:plant-seed, /gsd:thread,
  /gsd:add-backlog, /gsd:review-backlog, /gsd:pr-branch)
- Security hardening (security.cjs, prompt guard hook, workflow guard hook)
- Multi-repo workspace support, discussion audit trail, advisor mode
- New config options (research_before_questions, hooks.workflow_guard)
- Updated component counts in ARCHITECTURE.md

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
2026-03-20 12:21:53 -04:00
parent 47cb2b5c16
commit d5f2a7ea19
6 changed files with 485 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

143
docs/USER-GUIDE.md
View File

@@ -8,6 +8,8 @@ A detailed reference for workflows, troubleshooting, and configuration. For quic
- [Workflow Diagrams](#workflow-diagrams)
- [UI Design Contract](#ui-design-contract)
- [Backlog & Threads](#backlog--threads)
- [Security](#security)
- [Command Reference](#command-reference)
- [Configuration Reference](#configuration-reference)
- [Usage Examples](#usage-examples)
@@ -237,6 +239,72 @@ Controlled by `workflow.ui_safety_gate` config toggle.
---
## Backlog & Threads
### Backlog Parking Lot
Ideas that aren't ready for active planning go into the backlog using 999.x numbering, keeping them outside the active phase sequence.
```
/gsd:add-backlog "GraphQL API layer" # Creates 999.1-graphql-api-layer/
/gsd:add-backlog "Mobile responsive" # Creates 999.2-mobile-responsive/
```
Backlog items get full phase directories, so you can use `/gsd:discuss-phase 999.1` to explore an idea further or `/gsd:plan-phase 999.1` when it's ready.
**Review and promote** with `/gsd:review-backlog` — it shows all backlog items and lets you promote (move to active sequence), keep (leave in backlog), or remove (delete).
### Seeds
Seeds are forward-looking ideas with trigger conditions. Unlike backlog items, seeds surface automatically when the right milestone arrives.
```
/gsd:plant-seed "Add real-time collab when WebSocket infra is in place"
```
Seeds preserve the full WHY and WHEN to surface. `/gsd:new-milestone` scans all seeds and presents matches.
**Storage:** `.planning/seeds/SEED-NNN-slug.md`
### Persistent Context Threads
Threads are lightweight cross-session knowledge stores for work that spans multiple sessions but doesn't belong to any specific phase.
```
/gsd:thread # List all threads
/gsd:thread fix-deploy-key-auth # Resume existing thread
/gsd:thread "Investigate TCP timeout" # Create new thread
```
Threads are lighter weight than `/gsd:pause-work` — no phase state, no plan context. Each thread file includes Goal, Context, References, and Next Steps sections.
Threads can be promoted to phases (`/gsd:add-phase`) or backlog items (`/gsd:add-backlog`) when they mature.
**Storage:** `.planning/threads/{slug}.md`
---
## Security
### Defense-in-Depth (v1.27)
GSD generates markdown files that become LLM system prompts. This means any user-controlled text flowing into planning artifacts is a potential indirect prompt injection vector. v1.27 introduced centralized security hardening:
**Path Traversal Prevention:**
All user-supplied file paths (`--text-file`, `--prd`) are validated to resolve within the project directory. macOS `/var` → `/private/var` symlink resolution is handled.
**Prompt Injection Detection:**
The `security.cjs` module scans for known injection patterns (role overrides, instruction bypasses, system tag injections) in user-supplied text before it enters planning artifacts.
**Runtime Hooks:**
- `gsd-prompt-guard.js` — Scans Write/Edit calls to `.planning/` for injection patterns (always active, advisory-only)
- `gsd-workflow-guard.js` — Warns on file edits outside GSD workflow context (opt-in via `hooks.workflow_guard`)
**CI Scanner:**
`prompt-injection-scan.test.cjs` scans all agent, workflow, and command files for embedded injection vectors. Run as part of the test suite.
---
### Execution Wave Coordination
```
@@ -289,6 +357,7 @@ Controlled by `workflow.ui_safety_gate` config toggle.
| `/gsd:execute-phase <N>` | Execute all plans in parallel waves | After planning is complete |
| `/gsd:verify-work [N]` | Manual UAT with auto-diagnosis | After execution completes |
| `/gsd:ship [N]` | Create PR from verified work | After verification passes |
| `/gsd:fast <text>` | Inline trivial tasks — skips planning entirely | Typo fixes, config changes, small refactors |
| `/gsd:next` | Auto-detect state and run next step | Anytime — "what should I do next?" |
| `/gsd:ui-review [N]` | Retroactive 6-pillar visual audit | After execution or verify-work (frontend projects) |
| `/gsd:audit-milestone` | Verify milestone met its definition of done | Before completing milestone |
@@ -331,6 +400,23 @@ Controlled by `workflow.ui_safety_gate` config toggle.
| `/gsd:set-profile <profile>` | Quick profile switch | Change cost/quality tradeoff |
| `/gsd:reapply-patches` | Restore local modifications after update | After `/gsd:update` if you had local edits |
### Code Quality & Review
| Command | Purpose | When to Use |
|---------|---------|-------------|
| `/gsd:review --phase N` | Cross-AI peer review from external CLIs | Before executing, to validate plans |
| `/gsd:pr-branch` | Clean PR branch filtering `.planning/` commits | Before creating PR with planning-free diff |
| `/gsd:audit-uat` | Audit verification debt across all phases | Before milestone completion |
### Backlog & Threads
| Command | Purpose | When to Use |
|---------|---------|-------------|
| `/gsd:add-backlog <desc>` | Add idea to backlog parking lot (999.x) | Ideas not ready for active planning |
| `/gsd:review-backlog` | Promote/keep/remove backlog items | Before new milestone, to prioritize |
| `/gsd:plant-seed <idea>` | Forward-looking idea with trigger conditions | Ideas that should surface at a future milestone |
| `/gsd:thread [name]` | Persistent context threads | Cross-session work outside the phase structure |
---
## Configuration Reference
@@ -354,15 +440,20 @@ GSD stores project settings in `.planning/config.json`. Configure during `/gsd:n
"verifier": true,
"nyquist_validation": true,
"ui_phase": true,
"ui_safety_gate": true
"ui_safety_gate": true,
"research_before_questions": false
},
"git": {
"branching_strategy": "none",
"phase_branch_template": "gsd/phase-{phase}-{slug}",
"milestone_branch_template": "gsd/{milestone}-{slug}",
"quick_branch_template": null
}
}
"hooks": {
"context_warnings": true,
"workflow_guard": false
},
"git": {
"branching_strategy": "none",
"phase_branch_template": "gsd/phase-{phase}-{slug}",
"milestone_branch_template": "gsd/{milestone}-{slug}",
"quick_branch_template": null
}
}
```
### Core Settings
@@ -392,17 +483,25 @@ GSD stores project settings in `.planning/config.json`. Configure during `/gsd:n
| `workflow.nyquist_validation` | `true`, `false` | `true` | Validation architecture research during plan-phase; 8th plan-check dimension |
| `workflow.ui_phase` | `true`, `false` | `true` | Generate UI design contracts for frontend phases |
| `workflow.ui_safety_gate` | `true`, `false` | `true` | plan-phase prompts to run /gsd:ui-phase for frontend phases |
| `workflow.research_before_questions` | `true`, `false` | `false` | Run research before discussion questions instead of after |
Disable these to speed up phases in familiar domains or when conserving tokens.
### Hook Settings
| Setting | Options | Default | What it Controls |
|---------|---------|---------|------------------|
| `hooks.context_warnings` | `true`, `false` | `true` | Context window usage warnings |
| `hooks.workflow_guard` | `true`, `false` | `false` | Warn on file edits outside GSD workflow context |
Disable workflow toggles to speed up phases in familiar domains or when conserving tokens.
### Git Branching
| Setting | Options | Default | What it Controls |
|---------|---------|---------|------------------|
| `git.branching_strategy` | `none`, `phase`, `milestone` | `none` | When and how branches are created |
| `git.phase_branch_template` | Template string | `gsd/phase-{phase}-{slug}` | Branch name for phase strategy |
| `git.milestone_branch_template` | Template string | `gsd/{milestone}-{slug}` | Branch name for milestone strategy |
| `git.quick_branch_template` | Template string or `null` | `null` | Optional branch name for `/gsd:quick` tasks |
| `git.branching_strategy` | `none`, `phase`, `milestone` | `none` | When and how branches are created |
| `git.phase_branch_template` | Template string | `gsd/phase-{phase}-{slug}` | Branch name for phase strategy |
| `git.milestone_branch_template` | Template string | `gsd/{milestone}-{slug}` | Branch name for milestone strategy |
| `git.quick_branch_template` | Template string or `null` | `null` | Optional branch name for `/gsd:quick` tasks |
**Branching strategies explained:**
@@ -412,15 +511,15 @@ Disable these to speed up phases in familiar domains or when conserving tokens.
| `phase` | At each `execute-phase` | One phase per branch | Code review per phase, granular rollback |
| `milestone` | At first `execute-phase` | All phases share one branch | Release branches, PR per version |
**Template variables:** `{phase}` = zero-padded number (e.g., "03"), `{slug}` = lowercase hyphenated name, `{milestone}` = version (e.g., "v1.0"), `{num}` / `{quick}` = quick task ID (e.g., "260317-abc").
Example quick-task branching:
```json
"git": {
"quick_branch_template": "gsd/quick-{num}-{slug}"
}
```
**Template variables:** `{phase}` = zero-padded number (e.g., "03"), `{slug}` = lowercase hyphenated name, `{milestone}` = version (e.g., "v1.0"), `{num}` / `{quick}` = quick task ID (e.g., "260317-abc").
Example quick-task branching:
```json
"git": {
"quick_branch_template": "gsd/quick-{num}-{slug}"
}
```
### Model Profiles (Per-Agent Breakdown)