From 09335c491638c5382814955c86bbebb68dc84f3e Mon Sep 17 00:00:00 2001 From: xarmian Date: Sun, 21 Jun 2026 10:39:58 -0400 Subject: [PATCH] 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 --- internal/mcp/instructions.md | 6 ++++++ skills/pad/SKILL.md | 2 +- 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/internal/mcp/instructions.md b/internal/mcp/instructions.md index 12050bd6..f6732841 100644 --- a/internal/mcp/instructions.md +++ b/internal/mcp/instructions.md @@ -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: ""}` (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. diff --git a/skills/pad/SKILL.md b/skills/pad/SKILL.md index 0e1104ed..5692b51e 100644 --- a/skills/pad/SKILL.md +++ b/skills/pad/SKILL.md @@ -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 `. - `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 `_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.