feat: community-requested commands — /gsd:review, /gsd:plant-seed, /gsd:pr-branch

Three commands reimplemented from positively-received community PRs:

1. /gsd:review (#925) — Cross-AI peer review
   Invoke external AI CLIs (Gemini, Claude, Codex) to independently
   review phase plans. Produces REVIEWS.md with per-reviewer feedback
   and consensus summary. Feed back into planning via --reviews flag.
   Multiple users praised the adversarial review concept.

2. /gsd:plant-seed (#456) — Forward-looking idea capture
   Capture ideas with trigger conditions that auto-surface during
   /gsd:new-milestone. Seeds preserve WHY, WHEN to surface, and
   breadcrumbs to related code. Better than deferred items because
   triggers are checked, not forgotten.

3. /gsd:pr-branch (#470) — Clean PR branches
   Create a branch for pull requests by filtering out .planning/
   commits. Classifies commits as code-only, planning-only, or mixed,
   then cherry-picks only code changes. Reviewers see clean diffs.

All three are standalone command+workflow additions with no core code
changes. Help workflow updated. Test skill counts updated.

797/797 tests pass.
This commit is contained in:
Tom Boucher
2026-03-18 23:53:13 -04:00
parent 5fd384f336
commit c41a9f5908
8 changed files with 652 additions and 2 deletions

View File

@@ -0,0 +1,28 @@
---
name: gsd:plant-seed
description: Capture a forward-looking idea with trigger conditions — surfaces automatically at the right milestone
argument-hint: "[idea summary]"
allowed-tools:
- Read
- Write
- Edit
- Bash
- AskUserQuestion
---
<objective>
Capture an idea that's too big for now but should surface automatically when the right
milestone arrives. Seeds solve context rot: instead of a one-liner in Deferred that nobody
reads, a seed preserves the full WHY, WHEN to surface, and breadcrumbs to details.
Creates: .planning/seeds/SEED-NNN-slug.md
Consumed by: /gsd:new-milestone (scans seeds and presents matches)
</objective>
<execution_context>
@~/.claude/get-shit-done/workflows/plant-seed.md
</execution_context>
<process>
Execute the plant-seed workflow from @~/.claude/get-shit-done/workflows/plant-seed.md end-to-end.
</process>

25
commands/gsd/pr-branch.md Normal file
View File

@@ -0,0 +1,25 @@
---
name: gsd:pr-branch
description: Create a clean PR branch by filtering out .planning/ commits — ready for code review
argument-hint: "[target branch, default: main]"
allowed-tools:
- Bash
- Read
- AskUserQuestion
---
<objective>
Create a clean branch suitable for pull requests by filtering out .planning/ commits
from the current branch. Reviewers see only code changes, not GSD planning artifacts.
This solves the problem of PR diffs being cluttered with PLAN.md, SUMMARY.md, STATE.md
changes that are irrelevant to code review.
</objective>
<execution_context>
@~/.claude/get-shit-done/workflows/pr-branch.md
</execution_context>
<process>
Execute the pr-branch workflow from @~/.claude/get-shit-done/workflows/pr-branch.md end-to-end.
</process>

37
commands/gsd/review.md Normal file
View File

@@ -0,0 +1,37 @@
---
name: gsd:review
description: Request cross-AI peer review of phase plans from external AI CLIs
argument-hint: "--phase N [--gemini] [--claude] [--codex] [--all]"
allowed-tools:
- Read
- Write
- Bash
- Glob
- Grep
---
<objective>
Invoke external AI CLIs (Gemini, Claude, Codex) to independently review phase plans.
Produces a structured REVIEWS.md with per-reviewer feedback that can be fed back into
planning via /gsd:plan-phase --reviews.
**Flow:** Detect CLIs → Build review prompt → Invoke each CLI → Collect responses → Write REVIEWS.md
</objective>
<execution_context>
@~/.claude/get-shit-done/workflows/review.md
</execution_context>
<context>
Phase number: extracted from $ARGUMENTS (required)
**Flags:**
- `--gemini` — Include Gemini CLI review
- `--claude` — Include Claude CLI review (uses separate session)
- `--codex` — Include Codex CLI review
- `--all` — Include all available CLIs
</context>
<process>
Execute the review workflow from @~/.claude/get-shit-done/workflows/review.md end-to-end.
</process>

View File

@@ -337,6 +337,40 @@ Prerequisites: Phase verified, `gh` CLI installed and authenticated.
Usage: `/gsd:ship 4` or `/gsd:ship 4 --draft`
---
**`/gsd:review --phase N [--gemini] [--claude] [--codex] [--all]`**
Cross-AI peer review — invoke external AI CLIs to independently review phase plans.
- Detects available CLIs (gemini, claude, codex)
- Each CLI reviews plans independently with the same structured prompt
- Produces REVIEWS.md with per-reviewer feedback and consensus summary
- Feed reviews back into planning: `/gsd:plan-phase N --reviews`
Usage: `/gsd:review --phase 3 --all`
---
**`/gsd:pr-branch [target]`**
Create a clean branch for pull requests by filtering out .planning/ commits.
- Classifies commits: code-only (include), planning-only (exclude), mixed (include sans .planning/)
- Cherry-picks code commits onto a clean branch
- Reviewers see only code changes, no GSD artifacts
Usage: `/gsd:pr-branch` or `/gsd:pr-branch main`
---
**`/gsd:plant-seed [idea]`**
Capture a forward-looking idea with trigger conditions for automatic surfacing.
- Seeds preserve WHY, WHEN to surface, and breadcrumbs to related code
- Auto-surfaces during `/gsd:new-milestone` when trigger conditions match
- Better than deferred items — triggers are checked, not forgotten
Usage: `/gsd:plant-seed "add real-time notifications when we build the events system"`
### Milestone Auditing
**`/gsd:audit-milestone [version]`**

View File

@@ -0,0 +1,169 @@
<purpose>
Capture a forward-looking idea as a structured seed file with trigger conditions.
Seeds auto-surface during /gsd:new-milestone when trigger conditions match the
new milestone's scope.
Seeds beat deferred items because they:
- Preserve WHY the idea matters (not just WHAT)
- Define WHEN to surface (trigger conditions, not manual scanning)
- Track breadcrumbs (code references, related decisions)
- Auto-present at the right time via new-milestone scan
</purpose>
<process>
<step name="parse_idea">
Parse `$ARGUMENTS` for the idea summary.
If empty, ask:
```
What's the idea? (one sentence)
```
Store as `$IDEA`.
</step>
<step name="create_seed_dir">
```bash
mkdir -p .planning/seeds
```
</step>
<step name="gather_context">
Ask focused questions to build a complete seed:
```
AskUserQuestion(
header: "Trigger",
question: "When should this idea surface? (e.g., 'when we add user accounts', 'next major version', 'when performance becomes a priority')",
options: [] // freeform
)
```
Store as `$TRIGGER`.
```
AskUserQuestion(
header: "Why",
question: "Why does this matter? What problem does it solve or what opportunity does it create?",
options: []
)
```
Store as `$WHY`.
```
AskUserQuestion(
header: "Scope",
question: "How big is this? (rough estimate)",
options: [
{ label: "Small", description: "A few hours — could be a quick task" },
{ label: "Medium", description: "A phase or two — needs planning" },
{ label: "Large", description: "A full milestone — significant effort" }
]
)
```
Store as `$SCOPE`.
</step>
<step name="collect_breadcrumbs">
Search the codebase for relevant references:
```bash
# Find files related to the idea keywords
grep -rl "$KEYWORD" --include="*.ts" --include="*.js" --include="*.md" . 2>/dev/null | head -10
```
Also check:
- Current STATE.md for related decisions
- ROADMAP.md for related phases
- todos/ for related captured ideas
Store relevant file paths as `$BREADCRUMBS`.
</step>
<step name="generate_seed_id">
```bash
# Find next seed number
EXISTING=$(ls .planning/seeds/SEED-*.md 2>/dev/null | wc -l)
NEXT=$((EXISTING + 1))
PADDED=$(printf "%03d" $NEXT)
```
Generate slug from idea summary.
</step>
<step name="write_seed">
Write `.planning/seeds/SEED-{PADDED}-{slug}.md`:
```markdown
---
id: SEED-{PADDED}
status: dormant
planted: {ISO date}
planted_during: {current milestone/phase from STATE.md}
trigger_when: {$TRIGGER}
scope: {$SCOPE}
---
# SEED-{PADDED}: {$IDEA}
## Why This Matters
{$WHY}
## When to Surface
**Trigger:** {$TRIGGER}
This seed should be presented during `/gsd:new-milestone` when the milestone
scope matches any of these conditions:
- {trigger condition 1}
- {trigger condition 2}
## Scope Estimate
**{$SCOPE}** — {elaboration based on scope choice}
## Breadcrumbs
Related code and decisions found in the current codebase:
{list of $BREADCRUMBS with file paths}
## Notes
{any additional context from the current session}
```
</step>
<step name="commit_seed">
```bash
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs: plant seed — {$IDEA}" --files .planning/seeds/SEED-{PADDED}-{slug}.md
```
</step>
<step name="confirm">
```
✅ Seed planted: SEED-{PADDED}
"{$IDEA}"
Trigger: {$TRIGGER}
Scope: {$SCOPE}
File: .planning/seeds/SEED-{PADDED}-{slug}.md
This seed will surface automatically when you run /gsd:new-milestone
and the milestone scope matches the trigger condition.
```
</step>
</process>
<success_criteria>
- [ ] Seed file created in .planning/seeds/
- [ ] Frontmatter includes status, trigger, scope
- [ ] Breadcrumbs collected from codebase
- [ ] Committed to git
- [ ] User shown confirmation with trigger info
</success_criteria>

View File

@@ -0,0 +1,129 @@
<purpose>
Create a clean branch for pull requests by filtering out .planning/ commits.
The PR branch contains only code changes — reviewers don't see GSD artifacts
(PLAN.md, SUMMARY.md, STATE.md, CONTEXT.md, etc.).
Uses git cherry-pick with path filtering to rebuild a clean history.
</purpose>
<process>
<step name="detect_state">
Parse `$ARGUMENTS` for target branch (default: `main`).
```bash
CURRENT_BRANCH=$(git branch --show-current)
TARGET=${1:-main}
```
Check preconditions:
- Must be on a feature branch (not main/master)
- Must have commits ahead of target
```bash
AHEAD=$(git rev-list --count "$TARGET".."$CURRENT_BRANCH" 2>/dev/null)
if [ "$AHEAD" = "0" ]; then
echo "No commits ahead of $TARGET — nothing to filter."
exit 0
fi
```
Display:
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GSD ► PR BRANCH
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Branch: {CURRENT_BRANCH}
Target: {TARGET}
Commits: {AHEAD} ahead
```
</step>
<step name="analyze_commits">
Classify commits:
```bash
# Get all commits ahead of target
git log --oneline "$TARGET".."$CURRENT_BRANCH" --no-merges
```
For each commit, check if it ONLY touches .planning/ files:
```bash
# For each commit hash
FILES=$(git diff-tree --no-commit-id --name-only -r $HASH)
ALL_PLANNING=$(echo "$FILES" | grep -v "^\.planning/" | wc -l)
```
Classify:
- **Code commits**: Touch at least one non-.planning/ file → INCLUDE
- **Planning-only commits**: Touch only .planning/ files → EXCLUDE
- **Mixed commits**: Touch both → INCLUDE (planning changes come along)
Display analysis:
```
Commits to include: {N} (code changes)
Commits to exclude: {N} (planning-only)
Mixed commits: {N} (code + planning — included)
```
</step>
<step name="create_pr_branch">
```bash
PR_BRANCH="${CURRENT_BRANCH}-pr"
# Create PR branch from target
git checkout -b "$PR_BRANCH" "$TARGET"
```
Cherry-pick only code commits (in order):
```bash
for HASH in $CODE_COMMITS; do
git cherry-pick "$HASH" --no-commit
# Remove any .planning/ files that came along in mixed commits
git rm -r --cached .planning/ 2>/dev/null || true
git commit -C "$HASH"
done
```
Return to original branch:
```bash
git checkout "$CURRENT_BRANCH"
```
</step>
<step name="verify">
```bash
# Verify no .planning/ files in PR branch
PLANNING_FILES=$(git diff --name-only "$TARGET".."$PR_BRANCH" | grep "^\.planning/" | wc -l)
TOTAL_FILES=$(git diff --name-only "$TARGET".."$PR_BRANCH" | wc -l)
PR_COMMITS=$(git rev-list --count "$TARGET".."$PR_BRANCH")
```
Display results:
```
✅ PR branch created: {PR_BRANCH}
Original: {AHEAD} commits, {ORIGINAL_FILES} files
PR branch: {PR_COMMITS} commits, {TOTAL_FILES} files
Planning files: {PLANNING_FILES} (should be 0)
Next steps:
git push origin {PR_BRANCH}
gh pr create --base {TARGET} --head {PR_BRANCH}
Or use /gsd:ship to create the PR automatically.
```
</step>
</process>
<success_criteria>
- [ ] PR branch created from target
- [ ] Planning-only commits excluded
- [ ] No .planning/ files in PR branch diff
- [ ] Commit messages preserved from original
- [ ] User shown next steps
</success_criteria>

View File

@@ -0,0 +1,228 @@
<purpose>
Cross-AI peer review — invoke external AI CLIs to independently review phase plans.
Each CLI gets the same prompt (PROJECT.md context, phase plans, requirements) and
produces structured feedback. Results are combined into REVIEWS.md for the planner
to incorporate via --reviews flag.
This implements adversarial review: different AI models catch different blind spots.
A plan that survives review from 2-3 independent AI systems is more robust.
</purpose>
<process>
<step name="detect_clis">
Check which AI CLIs are available on the system:
```bash
# Check each CLI
command -v gemini >/dev/null 2>&1 && echo "gemini:available" || echo "gemini:missing"
command -v claude >/dev/null 2>&1 && echo "claude:available" || echo "claude:missing"
command -v codex >/dev/null 2>&1 && echo "codex:available" || echo "codex:missing"
```
Parse flags from `$ARGUMENTS`:
- `--gemini` → include Gemini
- `--claude` → include Claude
- `--codex` → include Codex
- `--all` → include all available
- No flags → include all available
If no CLIs are available:
```
No external AI CLIs found. Install at least one:
- gemini: https://github.com/google-gemini/gemini-cli
- codex: https://github.com/openai/codex
- claude: https://github.com/anthropics/claude-code
Then run /gsd:review again.
```
Exit.
If only one CLI is the current runtime (e.g. running inside Claude), skip it for the review
to ensure independence. At least one DIFFERENT CLI must be available.
</step>
<step name="gather_context">
Collect phase artifacts for the review prompt:
```bash
INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" init phase-op "${PHASE_ARG}")
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
```
Read from init: `phase_dir`, `phase_number`, `padded_phase`.
Then read:
1. `.planning/PROJECT.md` (first 80 lines — project context)
2. Phase section from `.planning/ROADMAP.md`
3. All `*-PLAN.md` files in the phase directory
4. `*-CONTEXT.md` if present (user decisions)
5. `*-RESEARCH.md` if present (domain research)
6. `.planning/REQUIREMENTS.md` (requirements this phase addresses)
</step>
<step name="build_prompt">
Build a structured review prompt:
```markdown
# Cross-AI Plan Review Request
You are reviewing implementation plans for a software project phase.
Provide structured feedback on plan quality, completeness, and risks.
## Project Context
{first 80 lines of PROJECT.md}
## Phase {N}: {phase name}
### Roadmap Section
{roadmap phase section}
### Requirements Addressed
{requirements for this phase}
### User Decisions (CONTEXT.md)
{context if present}
### Research Findings
{research if present}
### Plans to Review
{all PLAN.md contents}
## Review Instructions
Analyze each plan and provide:
1. **Summary** — One-paragraph assessment
2. **Strengths** — What's well-designed (bullet points)
3. **Concerns** — Potential issues, gaps, risks (bullet points with severity: HIGH/MEDIUM/LOW)
4. **Suggestions** — Specific improvements (bullet points)
5. **Risk Assessment** — Overall risk level (LOW/MEDIUM/HIGH) with justification
Focus on:
- Missing edge cases or error handling
- Dependency ordering issues
- Scope creep or over-engineering
- Security considerations
- Performance implications
- Whether the plans actually achieve the phase goals
Output your review in markdown format.
```
Write to a temp file: `/tmp/gsd-review-prompt-{phase}.md`
</step>
<step name="invoke_reviewers">
For each selected CLI, invoke in sequence (not parallel — avoid rate limits):
**Gemini:**
```bash
gemini -p "$(cat /tmp/gsd-review-prompt-{phase}.md)" 2>/dev/null > /tmp/gsd-review-gemini-{phase}.md
```
**Claude (separate session):**
```bash
claude -p "$(cat /tmp/gsd-review-prompt-{phase}.md)" --no-input 2>/dev/null > /tmp/gsd-review-claude-{phase}.md
```
**Codex:**
```bash
codex -p "$(cat /tmp/gsd-review-prompt-{phase}.md)" 2>/dev/null > /tmp/gsd-review-codex-{phase}.md
```
If a CLI fails, log the error and continue with remaining CLIs.
Display progress:
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GSD ► CROSS-AI REVIEW — Phase {N}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
◆ Reviewing with {CLI}... done ✓
◆ Reviewing with {CLI}... done ✓
```
</step>
<step name="write_reviews">
Combine all review responses into `{phase_dir}/{padded_phase}-REVIEWS.md`:
```markdown
---
phase: {N}
reviewers: [gemini, claude, codex]
reviewed_at: {ISO timestamp}
plans_reviewed: [{list of PLAN.md files}]
---
# Cross-AI Plan Review — Phase {N}
## Gemini Review
{gemini review content}
---
## Claude Review
{claude review content}
---
## Codex Review
{codex review content}
---
## Consensus Summary
{synthesize common concerns across all reviewers}
### Agreed Strengths
{strengths mentioned by 2+ reviewers}
### Agreed Concerns
{concerns raised by 2+ reviewers — highest priority}
### Divergent Views
{where reviewers disagreed — worth investigating}
```
Commit:
```bash
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs: cross-AI review for phase {N}" --files {phase_dir}/{padded_phase}-REVIEWS.md
```
</step>
<step name="present_results">
Display summary:
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GSD ► REVIEW COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Phase {N} reviewed by {count} AI systems.
Consensus concerns:
{top 3 shared concerns}
Full review: {padded_phase}-REVIEWS.md
To incorporate feedback into planning:
/gsd:plan-phase {N} --reviews
```
Clean up temp files.
</step>
</process>
<success_criteria>
- [ ] At least one external CLI invoked successfully
- [ ] REVIEWS.md written with structured feedback
- [ ] Consensus summary synthesized from multiple reviewers
- [ ] Temp files cleaned up
- [ ] User knows how to use feedback (/gsd:plan-phase --reviews)
</success_criteria>

View File

@@ -625,7 +625,7 @@ describe('copyCommandsAsCopilotSkills', () => {
// Count gsd-* directories — should be 31
const dirs = fs.readdirSync(tempDir, { withFileTypes: true })
.filter(e => e.isDirectory() && e.name.startsWith('gsd-'));
assert.strictEqual(dirs.length, 43, `expected 43 skill folders, got ${dirs.length}`);
assert.strictEqual(dirs.length, 46, `expected 46 skill folders, got ${dirs.length}`);
} finally {
fs.rmSync(tempDir, { recursive: true });
}
@@ -1119,7 +1119,7 @@ const { execFileSync } = require('child_process');
const crypto = require('crypto');
const INSTALL_PATH = path.join(__dirname, '..', 'bin', 'install.js');
const EXPECTED_SKILLS = 43;
const EXPECTED_SKILLS = 46;
const EXPECTED_AGENTS = 16;
function runCopilotInstall(cwd) {