msd-core/gsd-core/workflows/onboard.md

/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:

_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${GSD_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${GSD_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
# 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:

{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:

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:

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:

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:

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:

{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:

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:

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:

{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:

{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:

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:

# 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:

gsd_run --cwd "$ONBOARDING_ROOT" query commit "docs: create onboarding summary" --files .planning/onboarding/SUMMARY.md

Continue to final status.

4. Final Status

Print:

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.