feat(onboard): active "want me to set it up?" offer on needs_onboarding (TASK-1850) (#742)

Convert the passive needs_onboarding nudge into an active, lead-with-it
offer, mirrored across both agent-instruction surfaces:

- SKILL.md: the nudge rule now leads with "Want me to set it up?" and
  codifies offer-not-auto-run + respect-a-decline-for-the-session.
- internal/mcp/instructions.md: previously had NO needs_onboarding rule at
  all, so pure-MCP agents got the bootstrap flag but were never told to act
  on it. Added a "New workspace: offer to set it up" section with the same
  offer wording, pointing at the pad_onboard prompt / pad_playbook get
  ref:onboard to actually run onboarding once accepted.

Agent offers, never auto-runs. Agent-instruction surfaces only.

Parent: PLAN-1847.

Claude-Session: https://claude.ai/code/session_01KmxkPxLksjf1pmrZDpsnTJ
This commit is contained in:
xarmian
2026-06-21 10:39:58 -04:00
committed by GitHub
parent 7962fabaeb
commit 09335c4916
2 changed files with 7 additions and 1 deletions
+6
View File
@@ -69,6 +69,12 @@ If the user references a workspace this connection can't see (you'll get a 403 f
For brand-new workspaces, `pad_workspace.create` with `{name: "<name>"}` (and optional `template`) creates the workspace AND auto-adds it to this connection's allow-list in one call — no claim code needed. Only works when the user granted "may create workspaces" at consent time; if that scope was declined the create call still succeeds but the workspace doesn't auto-join — direct the user to the claim flow above to bring it in.
## New workspace: offer to set it up
The bootstrap blob (from `pad_meta.action: bootstrap`, `pad_set_workspace`, or the `pad://workspace/{ws}/bootstrap` resource) carries `needs_onboarding: bool` — true when the workspace has zero user-created items (template seeds don't count). When it's true, **lead with an active offer before anything else**: *"This workspace is brand new and isn't set up yet. Want me to set it up? I'll ask a few quick questions and adapt it to your project."*
This is an **offer, not an auto-run** — wait for the user to say yes before running onboarding. If they accept, run the `onboard` playbook (use the `pad_onboard` prompt, or load the body via `pad_playbook` `action: get`, `ref: onboard`). If they decline, or already declined earlier in the session, respect that and skip the offer. The flag flips to false the moment any item exists, so it won't nag past first setup.
## Multi-step workflows
Four prompts ship with the server: `pad_plan`, `pad_ideate`, `pad_retro`, `pad_onboard`. Use them when the user wants help planning, brainstorming, retrospecting, or onboarding into a workspace — they encode the multi-step Pad-aware playbook for each.
+1 -1
View File
@@ -36,7 +36,7 @@ The returned `AgentBootstrap` blob carries everything the skill needs to start a
- `roles [...]` — agent roles configured in the workspace
- `playbooks [...]` — METADATA ONLY: `ref`, `title`, `slug`, `invocation_slug`, `trigger`, `scope`, `status`, `has_arguments`, `summary`. Full bodies load on invocation via `pad playbook show <slug>`.
- `dashboard {...}` — active items, attention, suggested next, recent activity. Five sub-arrays are capped to 5 entries each (`attention`, `recent_activity`, `active_items`, `active_plans`, `by_role`); each pairs with a `<name>_overflow_count` int field surfaced when truncation kicked in. Use `pad project dashboard` to pull the full set when any overflow > 0.
- `needs_onboarding: bool` — true when the workspace has zero user-created items (template seeds don't count). PLAN-1496 / TASK-1504. **When this is true, lead your response with a one-line nudge:** *"This workspace hasn't been set up yet — just say **set up my workspace** and I'll walk you through it."* Lead with the natural-language phrasing (it works on every surface); don't hardcode a slash command in the nudge, since this skill runs under Claude Code (`/pad`), Codex (`$pad`), and others. Then proceed with whatever else the user asked. The flag flips to false the moment any user/agent-created item exists; don't nag past that point. If the user has already declined onboarding (look at recent conversation), respect that and skip the nudge for this session.
- `needs_onboarding: bool` — true when the workspace has zero user-created items (template seeds don't count). PLAN-1496 / TASK-1504. **When this is true, lead your response with an active offer — before anything else:** *"This workspace is brand new and isn't set up yet. Want me to set it up? I'll ask a few quick questions and adapt it to your project."* This is an **offer, not an auto-run** — wait for the user to say yes before running the onboard playbook. If they say yes, run it (see the Onboarding routing entry). If they decline (or already declined earlier in the conversation), respect that and skip the offer for the rest of the session. Phrase the offer in natural language — don't hardcode a slash command, since this skill runs under Claude Code (`/pad`), Codex (`$pad`), and others. After offering, proceed with whatever else the user asked. The flag flips to false the moment any user/agent-created item exists; don't nag past that point.
If the conventions list includes items, treat them as project rules you must follow. The vocabulary depends on the workspace domain — a software workspace ships rules like "use conventional commit format," a hiring workspace ships rules like "anonymize candidate names in exports," a research workspace ships rules like "always cite sources." Follow whatever the workspace has configured.