Merge branch 'next' into feat/1820-specless-predicate-rail

This commit is contained in:
Tom Boucher
2026-07-07 07:49:07 -04:00
committed by GitHub
171 changed files with 5853 additions and 498 deletions

View File

@@ -40,8 +40,9 @@ Evaluate `$ARGUMENTS` against these routing rules. Apply the **first matching**
| If the text describes... | Route to | Why |
|--------------------------|----------|-----|
| Starting a new project, "set up", "initialize" | `/gsd:new-project` | Needs full project initialization |
| Mapping or analyzing an existing codebase | `/gsd:map-codebase` | Codebase discovery |
| Starting a new greenfield project, "set up", "initialize" | `/gsd:new-project` | Needs full project initialization |
| First-time setup for an existing codebase, brownfield onboarding | `/gsd:onboard` | Safe map → docs ingest → project setup sequence |
| Mapping or analyzing an existing codebase map | `/gsd:map-codebase` | Codebase discovery or refresh |
| A bug, error, crash, failure, or something broken | `/gsd:debug` | Needs systematic investigation |
| Spiking, "test if", "will this work", "experiment", "prove this out", validate feasibility | `/gsd:spike` | Throwaway experiment to validate feasibility |
| Sketching, "mockup", "what would this look like", "prototype the UI", "design this", explore visual direction | `/gsd:sketch` | Throwaway HTML mockups to explore design |
@@ -61,7 +62,7 @@ Evaluate `$ARGUMENTS` against these routing rules. Apply the **first matching**
| Completing a milestone, shipping, releasing | `/gsd:complete-milestone` | Milestone lifecycle |
| A specific, actionable, small task (add feature, fix typo, update config) | `/gsd:quick` | Self-contained, single executor |
**Requires `.planning/` directory:** All routes except `/gsd:new-project`, `/gsd:map-codebase`, `/gsd:spike`, `/gsd:sketch`, and `/gsd:help`. If the project doesn't exist and the route requires it, suggest `/gsd:new-project` first.
**Requires `.planning/` directory:** All routes except `/gsd:new-project`, `/gsd:onboard`, `/gsd:map-codebase`, `/gsd:spike`, `/gsd:sketch`, and `/gsd:help`. If the project doesn't exist and the route requires it, suggest `/gsd:onboard` for existing codebases or `/gsd:new-project` for greenfield projects.
**Ambiguity handling:** If the text could reasonably match multiple routes, ask the user via AskUserQuestion with the top 2-3 options. For example:

View File

@@ -7,7 +7,8 @@ One-liner refresher for returning users. Output ONLY the `<reference>` content b
```text
/gsd:new-project Initialize a project (greenfield)
/gsd:map-codebase Map an existing codebase (brownfield)
/gsd:onboard Onboard an existing codebase (brownfield)
/gsd:map-codebase Refresh/map codebase intelligence
/gsd:plan-phase <N> Create a phase plan
/gsd:execute-phase <N> Execute a phase
/gsd:progress Where am I, what's next

View File

@@ -11,11 +11,12 @@ Plan-driven development for solo agentic work with Claude Code. GSD Core turns a
```text
/gsd:new-project # Greenfield: questioning → research → requirements → roadmap
/gsd:onboard # Existing codebase: map → ingest docs → initialize planning
/gsd:plan-phase 1 # Create a detailed plan for phase 1
/gsd:execute-phase 1 # Execute all plans in the phase
```
Existing codebase? Run `/gsd:map-codebase` first to ground GSD in your code.
Existing codebase? Run `/gsd:onboard` to map the repo, ingest existing docs, and initialize planning safely.
## Common commands

View File

@@ -62,6 +62,16 @@ Creates all `.planning/` artifacts:
Usage: `/gsd:new-project`
**`/gsd:onboard [--fast] [--text]`**
Guide first-time onboarding for an existing codebase.
- Detects brownfield code, existing planning docs, and partial `.planning/` state
- Routes through `/gsd:map-codebase`, `/gsd:ingest-docs`, and `/gsd:new-project` in the safe order
- Creates `.planning/onboarding/SUMMARY.md` after project setup
- Idempotent: confirms existing artifacts and does not overwrite planning silently
Usage: `/gsd:onboard`
**`/gsd:map-codebase [--fast] [--focus <area>] [--query <term>]`**
Map an existing codebase for brownfield projects.
@@ -72,7 +82,7 @@ Map an existing codebase for brownfield projects.
- Analyzes codebase with parallel Explore agents
- Creates `.planning/codebase/` with 7 focused documents
- Covers stack, architecture, structure, conventions, testing, integrations, concerns
- Use before `/gsd:new-project` on existing codebases
- Usually reached through `/gsd:onboard` for first-time existing-codebase setup; run directly to refresh or focus a map
Usage: `/gsd:map-codebase`

View File

@@ -9,7 +9,7 @@ Emit a section from the full reference for the topic in `$ARGUMENTS`. Read `work
|---|---|
| `next`, `smart-entry` | `### Smart Entry` |
| `workflow`, `core`, `core-workflow` | `## Core Workflow` (entire section through end of `### Quick Mode`) |
| `init`, `new-project` | `### Project Initialization` |
| `init`, `new-project`, `onboard`, `onboarding`, `brownfield` | `### Project Initialization` |
| `map`, `map-codebase` | The `/gsd:map-codebase` block under `### Project Initialization` |
| `discuss`, `discuss-phase` | The `/gsd:discuss-phase` block under `### Phase Planning` |
| `plan`, `planning`, `plan-phase` | `### Phase Planning` |

View File

@@ -0,0 +1,277 @@
# /gsd:onboard Workflow
One-command onboarding for an existing or unknown repo. This workflow is a thin
renderer around `init onboard`; deterministic routing lives in the CLI projection.
@~/.claude/gsd-core/references/gsd-run-resolver.md
## 1. Render the Onboarding Projection
Parse `$ARGUMENTS`:
- `--fast` passes `--fast` to `init onboard`. Fast mode accepts the fast map for lightweight onboarding only; `next_action` still decides whether complete map work is required before project setup.
- `--text` forces text-mode choices for runtimes without `AskUserQuestion`.
Run the standard `gsd_run` resolver from the reference above, then run the projection from the runtime root:
```bash
# If --fast was parsed from $ARGUMENTS:
INIT=$(gsd_run --cwd "$_GSD_RUNTIME_ROOT" init onboard --fast --raw)
# Otherwise:
INIT=$(gsd_run --cwd "$_GSD_RUNTIME_ROOT" init onboard --raw)
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
```
Parse JSON fields from `INIT`:
- `next_action.kind`, `next_action.command`, `next_action.reason`, `next_action.missing`, `next_action.summary_path`
- `handoff_commands.ingest_docs`, `handoff_commands.manager`, `handoff_commands.new_project`, `handoff_commands.onboard`
- `map_readiness`, `codebase_map_summary_status`, `codebase_map_final_status`
- `planning_exists`, `project_exists`, `requirements_exists`, `roadmap_exists`, `state_exists`
- `is_brownfield`, `fast_mode`, `has_codebase_map`, `has_fast_codebase_map`
- `missing_codebase_map_files`, `missing_fast_codebase_map_files`
- `has_docs_candidates`, `doc_candidate_count`, `onboarding_summary_exists`
- `commit_docs`, `text_mode`, `has_git`, `git_worktree_root`, `in_nested_subdir`
Set:
- `TEXT_MODE=true` if `--text` is present or `text_mode` is true. When `TEXT_MODE` is active, replace every `AskUserQuestion` call below with a plain-text numbered list and ask the user to type their choice number — required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where `AskUserQuestion` is not available.
- `ONBOARDING_ROOT={git_worktree_root || _GSD_RUNTIME_ROOT}`.
If `has_git` and `in_nested_subdir` are true, warn that onboarding artifacts belong to the outer worktree at `git_worktree_root`. Do not run `git init`.
## 2. Execute `next_action`
### `map-codebase`
If `next_action.kind == "map-codebase"`:
- If `TEXT_MODE=true`, print:
```text
{next_action.reason}
Missing map files: {fast_mode ? missing_fast_codebase_map_files : missing_codebase_map_files}
1. Map codebase first — run {next_action.command} from worktree root {ONBOARDING_ROOT} (Recommended)
2. Skip mapping — continue with weaker onboarding context
Enter number:
```
- Otherwise use AskUserQuestion:
- header: "Codebase"
- question: "{next_action.reason} Map it first?"
- options:
- "Map codebase first" — Run `{next_action.command}` from worktree root `{ONBOARDING_ROOT}` (Recommended)
- "Skip mapping" — Continue with weaker onboarding context
If the user chooses mapping, do not nest the interactive workflow. Print:
```text
Run from worktree root {ONBOARDING_ROOT}:
{next_action.command}
Then rerun {handoff_commands.onboard} from the same worktree root.
```
Exit. If the user skips mapping:
- If `(project_exists || requirements_exists || roadmap_exists || state_exists) && (!project_exists || !requirements_exists || !roadmap_exists || !state_exists)`, route the skip to the partial planning guard instead:
```text
Skipping codebase mapping may give downstream steps weaker context, but project planning exists and is incomplete.
PROJECT.md: {project_exists ? "present" : "missing"}
REQUIREMENTS.md: {requirements_exists ? "present" : "missing"}
ROADMAP.md: {roadmap_exists ? "present" : "missing"}
STATE.md: {state_exists ? "present" : "missing"}
Run the appropriate lower-level command to fill the missing planning artifact(s), then rerun {handoff_commands.onboard}.
```
Exit.
- If `has_docs_candidates && !project_exists`, route the skip to docs ingest instead:
```text
Skipping codebase mapping may give downstream steps weaker context, but existing ADR/PRD/SPEC/RFC documents should still be ingested before {handoff_commands.new_project}.
Run from worktree root {ONBOARDING_ROOT}:
{handoff_commands.ingest_docs}
Then rerun {handoff_commands.onboard} from the same worktree root.
```
Exit.
- Otherwise print:
```text
Skipping codebase mapping may give {handoff_commands.new_project} weaker context.
Run from worktree root {ONBOARDING_ROOT}:
{handoff_commands.new_project}
Then rerun {handoff_commands.onboard} from the same worktree root.
```
Exit.
### `ingest-docs`
If `next_action.kind == "ingest-docs"`:
- If `TEXT_MODE=true`, print:
```text
{next_action.reason}
Detected {doc_candidate_count} possible ADR/PRD/SPEC/RFC document(s).
1. Ingest docs first — run {next_action.command} from worktree root {ONBOARDING_ROOT} (Recommended)
2. Skip docs ingest — continue to {handoff_commands.new_project}
Enter number:
```
- Otherwise use AskUserQuestion:
- header: "Docs"
- question: "Detected {doc_candidate_count} possible ADR/PRD/SPEC/RFC document(s). Ingest them first?"
- options:
- "Ingest docs first" — Run `{next_action.command}` from worktree root `{ONBOARDING_ROOT}` (Recommended)
- "Skip docs ingest" — Continue to `{handoff_commands.new_project}`
If the user chooses ingest, print:
```text
Run from worktree root {ONBOARDING_ROOT}:
{next_action.command}
Then rerun {handoff_commands.onboard} from the same worktree root.
```
Exit. If the user skips docs ingest, print:
```text
Skipping docs ingest may omit existing ADR/PRD/SPEC/RFC context from {handoff_commands.new_project}.
Run from worktree root {ONBOARDING_ROOT}:
{handoff_commands.new_project}
Then rerun {handoff_commands.onboard} from the same worktree root.
```
Exit.
### `complete-map-before-new-project`
If `next_action.kind == "complete-map-before-new-project"`, print:
```text
{next_action.reason}
Run from worktree root {ONBOARDING_ROOT}:
{next_action.command}
Then rerun {handoff_commands.onboard} from the same worktree root.
```
Exit.
### `new-project`
If `next_action.kind == "new-project"`, print:
```text
{next_action.reason}
Run from worktree root {ONBOARDING_ROOT}:
{next_action.command}
Then rerun {handoff_commands.onboard} from the same worktree root.
```
Exit.
### `partial-planning`
If `next_action.kind == "partial-planning"`, print:
```text
Project planning exists but is incomplete.
Missing files: {next_action.missing}
REQUIREMENTS.md: {requirements_exists ? "present" : "missing"}
ROADMAP.md: {roadmap_exists ? "present" : "missing"}
STATE.md: {state_exists ? "present" : "missing"}
Run the appropriate lower-level command to fill the missing planning artifact(s), then rerun {handoff_commands.onboard}.
```
Exit.
### `ready`
If `next_action.kind == "ready"`, print the final status section and exit.
### `write-summary`
If `next_action.kind == "write-summary"`, continue to summary creation.
## 3. Create Onboarding Summary
Create `{ONBOARDING_ROOT}/{next_action.summary_path}`. Do not overwrite an existing summary; the projection should only route here when the summary is missing.
Summary template:
```markdown
# Onboarding Summary
## Project State
- PROJECT.md: {project_exists ? "present" : "missing"}
- REQUIREMENTS.md: {requirements_exists ? "present" : "missing"}
- ROADMAP.md: {roadmap_exists ? "present" : "missing"}
- STATE.md: {state_exists ? "present" : "missing"}
## Codebase Context
- Brownfield repo: {is_brownfield ? "yes" : "no"}
- Map readiness: {map_readiness}
- Codebase map: {codebase_map_summary_status}
- Fast map available: {has_fast_codebase_map ? "yes" : "no"}
## Docs Context
- Existing ADR/PRD/SPEC/RFC candidates: {has_docs_candidates ? doc_candidate_count : 0}
## Recommended Next Step
- {handoff_commands.manager}
```
If `commit_docs` is true, commit only the summary path from the onboarding root:
```bash
gsd_run --cwd "$ONBOARDING_ROOT" query commit "docs: create onboarding summary" --files .planning/onboarding/SUMMARY.md
```
Continue to final status.
## 4. Final Status
Print:
```text
Onboarding status:
- PROJECT.md: {project_exists ? "present" : "missing"}
- REQUIREMENTS.md: {requirements_exists ? "present" : "missing"}
- ROADMAP.md: {roadmap_exists ? "present" : "missing"}
- STATE.md: {state_exists ? "present" : "missing"}
- Codebase map: {codebase_map_final_status}
- Onboarding summary: present
Next recommended command: {handoff_commands.manager}
```
Do not run implementation execution or shipping from onboarding.

View File

@@ -671,6 +671,26 @@ fi
**Step 6: Spawn executor**
Auto-degrade to sequential if HEAD has diverged from the worktree fork base (#1941, mirrors
execute-phase's #683/#1369 guard). Claude Code's `isolation="worktree"` forks new worktrees from
`origin/HEAD`, not the live local HEAD. If a prior quick task in this session (or the Step 5.6
pre-dispatch plan commit above) advanced local HEAD without an intervening `git push`,
`origin/HEAD` stays pinned to a stale ancestor and the executor's `worktree_branch_check` guard
halts with a base-mismatch fatal — potentially many commits behind, not just one. Run this check
immediately before capturing `EXPECTED_BASE` so it reflects the most current local state.
```bash
if [ "$RUNTIME" = "claude" ] && [ "${USE_WORKTREES:-true}" != "false" ]; then
_QUICK_SHOULD_DEGRADE=$(gsd_run query worktree.base-check --pick shouldDegrade 2>/dev/null || true)
if [ "$_QUICK_SHOULD_DEGRADE" = "true" ]; then
_QUICK_DEGRADE_MSG=$(gsd_run query worktree.base-check --pick message 2>/dev/null || true)
[ -n "$_QUICK_DEGRADE_MSG" ] && printf '%s\n' "$_QUICK_DEGRADE_MSG" >&2
echo "⚠ [#1941] Worktree fork base diverged from orchestrator HEAD — auto-degrading to sequential mode for this quick task to avoid a base-mismatch halt." >&2
USE_WORKTREES=false
fi
fi
```
Capture current HEAD before spawning (used for worktree branch check):
```bash
EXPECTED_BASE=$(git rev-parse HEAD)