7c07fce70f
* fix(#381): make gsd_run launcher reachable in fresh-shell-per-block runtimes On runtimes that execute each fenced bash block in a separate shell process (e.g. Claude Code — documented behavior: each Bash command is a separate process; inline shell functions and exported vars do not persist between calls), the once-per-file gsd_run() function was undefined in every block after the preamble block, and the call was swallowed by `2>/dev/null || echo "{}"` into silent empty state. Fix (budget-neutral session-level resolution): - Ship gsd-core/bin/gsd_run, a POSIX sh wrapper that symlink-resolves its own location and execs the co-located gsd-tools.cjs. Exposed on PATH via the npm `bin` field (global installs) and shipped to local installs via the recursive gsd-core/ copy. - The per-file launcher preamble now appends `export PATH='<bindir>':"$PATH"` to the file named by $CLAUDE_ENV_FILE (Claude Code's documented env-persistence mechanism) so later fresh-shell blocks resolve gsd_run from PATH. Guarded as a strict no-op when CLAUDE_ENV_FILE is unset; the inline gsd_run() definition remains the fallback for all other runtimes. The single-quoted dir neutralizes shell metacharacters at source time. - Propagated via scripts/sync-runtime-launcher.cjs to all launcher-using files. - XL workflow byte budget 93000 -> 93200 (the ~130B clause pushes plan-phase.md to 93135; legitimate content growth, ratchet-up per #717). Regression tests (I)/(J) in runtime-launcher-parity.test.cjs cover wrapper delegation and end-to-end PATH persistence (sourcing the env file with a space-bearing install path). Known limitation: an install path containing a literal single-quote yields a malformed env-file line and falls back to the status quo (no regression); rare on sanitized home directories. Closes #381 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(#381): add changeset for gsd_run fresh-shell reachability fix Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * test(#381): scope test (J) bare-PATH execution to POSIX (Windows Git Bash exec bit) Windows Git Bash (msys2) does not honor Node's chmod exec bit for PATH-executing extension-less scripts, so the bare `gsd_run` command lookup failed there even though the env-file PATH persistence was correct. The env-file content assertions (the fix's actual cross-platform logic) still run on every platform; only the final source-and-execute sub-step is gated to non-win32. Global installs on Windows are covered by npm's generated bin shim. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
12 KiB
12 KiB
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.
After writing the file, search the codebase for relevant references:
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
One-shot capture: the seed file is written immediately from the idea text alone. Trigger / Why / Scope are optional enrichment — they can be provided now or added later. The file is never gated behind questions.
Parse `$ARGUMENTS` for the idea summary.First, check for an enrich flag:
if echo "$ARGUMENTS" | grep -qE '\-\-enrich[[:space:]]+SEED-[0-9]+'; then
ENRICH_TARGET=$(echo "$ARGUMENTS" | grep -oE 'SEED-[0-9]+')
SEED_FILE=$(ls .planning/seeds/${ENRICH_TARGET}-*.md 2>/dev/null | head -1)
# Skip to enrich-seed step — do not prompt for $IDEA
else
if [ -n "$ARGUMENTS" ]; then
IDEA="$ARGUMENTS"
else
# Ask only when no arguments at all
# What's the idea? (one sentence)
IDEA="<user response>"
fi
fi
If $ENRICH_TARGET is set, skip straight to the enrich-seed step. Do not set $IDEA and do not run create-seed-dir, generate-seed-id, write-seed, collect-breadcrumbs, commit-seed, or confirm.
If $ARGUMENTS is non-empty and contains no --enrich flag, treat the full value as $IDEA (no prompt).
Only prompt for the idea when $ARGUMENTS is empty and no enrich target is present. Store the response as $IDEA.
Generate slug from idea summary.
Write `.planning/seeds/SEED-{PADDED}-{slug}.md` immediately with sensible defaults:trigger_when: default is"when relevant"— the seed will surface during any new-milestone scan; the user can narrow it later via--enrichscope: default is"unknown"— the user can update it via--enrich
---
id: SEED-{PADDED}
status: dormant
planted: {ISO date}
planted_during: {current milestone/phase from STATE.md, or "unknown" if not in a GSD project}
trigger_when: when relevant
scope: unknown
---
# SEED-{PADDED}: {$IDEA}
## Why This Matters
_To be filled in. Run `/gsd:capture --seed --enrich SEED-{PADDED}` to add context._
## When to Surface
**Trigger:** when relevant
This seed will surface during `/gsd:new-milestone` when the milestone scope matches.
## Scope Estimate
**Unknown** — run `/gsd:capture --seed --enrich SEED-{PADDED}` to estimate effort.
## Breadcrumbs
_No breadcrumbs collected yet._
## Notes
_Captured via one-shot seed capture. Enrich with trigger, why, and scope at your convenience._
Extract one or two key terms from $IDEA (the most distinctive noun or phrase) and store as $KEYWORD.
# Derive a single keyword for breadcrumb search.
# Lower-case, strip punctuation, take the first token longer than 2 chars.
KEYWORD=$(printf '%s' "$IDEA" \
| tr '[:upper:]' '[:lower:]' \
| tr -cs 'a-z0-9' '\n' \
| awk 'length > 2 {print; exit}')
KEYWORD="${KEYWORD:-seed}" # fallback to literal "seed" if extraction yields nothing
# Find files related to the idea keywords ($KEYWORD derived from $IDEA)
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
If any breadcrumbs are found, update the Breadcrumbs section of the seed file.
Store relevant file paths as $BREADCRUMBS.
"{$IDEA}" File: .planning/seeds/SEED-{PADDED}-{slug}.md
Trigger and scope are set to defaults. Run /gsd:capture --seed --enrich SEED-{PADDED}
to add trigger conditions, rationale, and scope estimate at your convenience.
This seed will surface automatically when you run /gsd:new-milestone.
</step>
<step name="enrich-seed">
**Optional enrichment — only run this step when `--enrich` flag is present.**
If `--enrich` flag is in `$ARGUMENTS`:
- `$ENRICH_TARGET` and `$SEED_FILE` are already set by `parse-idea`. Derive `$SEED_ID` from `$ENRICH_TARGET` (e.g. `SEED_ID="$ENRICH_TARGET"`). If `$SEED_FILE` is empty, fall back to the most-recently modified file in `.planning/seeds/` and set `$SEED_ID` from its filename.
- Ask focused questions to build a complete seed:
**Text mode (`workflow.text_mode: true` in config or `--text` flag):** Set `TEXT_MODE=true` if `--text` is present in `$ARGUMENTS` OR `text_mode` from init JSON is `true`. When TEXT_MODE is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where `AskUserQuestion` is not available.
```text
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.
Update the seed file's frontmatter and sections with the gathered values:
- Set
trigger_when: {$TRIGGER} - Set
scope: {$SCOPE} - Fill in
## Why This Matterswith{$WHY} - Fill in
## When to Surfacetrigger detail - Fill in
## Scope Estimateelaboration
Commit the update:
gsd_run query commit "docs: enrich seed ${SEED_ID} — trigger + why + scope" --files "$SEED_FILE"
Confirm:
✅ Seed enriched: ${SEED_ID}
Trigger: {$TRIGGER}
Scope: {$SCOPE}
<success_criteria>
- Seed file created in .planning/seeds/ in one step, no questions required
- Frontmatter includes status, trigger_when (default: "when relevant"), scope (default: "unknown")
- File is written BEFORE any optional enrichment questions are asked
- Committed to git
- User shown confirmation with file path
- Optional --enrich path available for adding trigger, why, scope post-capture </success_criteria>