Merge branch 'next' into feat/1820-specless-predicate-rail
This commit is contained in:
@@ -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:
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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`
|
||||
|
||||
|
||||
@@ -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` |
|
||||
|
||||
277
gsd-core/workflows/onboard.md
Normal file
277
gsd-core/workflows/onboard.md
Normal 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.
|
||||
@@ -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)
|
||||
|
||||
Reference in New Issue
Block a user