Epic: Turn a task or PR URL into a ready workspace with gw grab

[nicksong-z]

Problem

The current gw create workflow is fast once the user already knows the workspace name, repository set, branch, tracking mode, and source metadata. In practice, that information often already exists in a pull request, issue, or task URL.

Users still have to translate the source into Grove flags by hand:

gw create feat-data-status \
  -r conversational-analytics \
  -b feat/data-source-status \
  --track \
  --source-url ... \
  --source-provider github \
  --source-ref 1172 \
  --source-title ...

The desired experience is:

gw grab https://github.com/acme/api/pull/123

Goal

Turn an external task or PR URL into a reviewed creation plan and then a ready-to-work Grove workspace, without teaching Grove core about GitHub, GitLab, Linear, Notion, Slack, or any coding agent.

This should become Grove's flagship workflow: task → safe multi-repo workspace.

Proposed user flow

1. User runs gw grab <url>.
2. A resolver identifies source metadata, primary repository, branch, and whether the branch should be tracked.
3. Grove maps the canonical remote to a discovered local repository, cloning it if needed.
4. Grove suggests a workspace name and repository set:
   • the primary repository is always included;
   • the user may choose a preset or additional repositories;
   • only the primary repository tracks the source branch, while sibling repos create the same branch from their configured bases.
5. Grove prints a concise plan and asks for confirmation.
6. The existing workspace service creates the workspace, runs setup, records provenance, and reports readiness/failures.
7. When --agent <name> is requested, Grove composes the containerized handoff from Grove 1.2: Containerized agent workspaces and handoff #64 rather than implementing an agent runtime in gw-grab.

Example plan:

Source:     GitHub PR #123 — Add data-source status
Workspace:  feat-data-source-status
Branch:     feat/data-source-status
Repos:
  api       track origin/feat/data-source-status
  web       create from origin/main
  contracts create from origin/main

Architecture

Provider-specific URL resolution belongs in a plugin, not Grove core.

Suggested shape:

• A reference gw-grab plugin implements the user-facing command and GitHub PR resolver first.
• Define a small, versioned resolver result schema containing:
  • source provider, URL, ref, and title;
  • canonical primary repo remote;
  • branch and branch mode;
  • suggested workspace name;
  • optional warnings or provider-specific limitations.
• The plugin composes existing stable Grove commands/JSON rather than duplicating worktree orchestration.
• If a small core API is needed, keep it provider-neutral and route it through the same workspace lifecycle used by the CLI.

Existing primitives from #48/v1.1.8 already provide most of the foundation: --track, per-repo tracking, source provenance, git URL cloning, and gw repos --json.

MVP: GitHub pull requests

• Create and release the gw-grab reference plugin.
• Resolve a public or authenticated GitHub PR using gh.
• Match owner/repo to a local clone via canonical remote identity.
• Clone a missing primary repo into the configured repo directory.
• Suggest workspace name, branch, source metadata, and tracking mode.
• Allow optional preset/additional-repo selection.
• Print a plan and require confirmation unless --yes is passed.
• Delegate creation to Grove and preserve source provenance.
• Provide useful behavior for fork PRs, missing/deleted remote branches, and ambiguous local clones.

Acceptance criteria

• After plugin installation, gw grab <github-pr-url> creates a usable workspace without requiring manual repo or branch flags.
• The primary repo contains the PR branch and tracks the correct upstream when possible.
• Additional repos use the same branch name from their configured base branches.
• gw status --format json preserves the original source metadata.
• The plan can be consumed non-interactively and failures return non-zero status.
• Resolver and orchestration behavior have unit and e2e coverage.
• Typical resolution + workspace creation completes in under 30 seconds, excluding user-defined setup hooks and large first-time clones.

Later providers

Only add these after the GitHub PR flow demonstrates real usage:

• GitHub issues
• GitLab merge requests/issues
• Linear/Jira tasks
• Notion/Slack sources

Each should reuse the same resolver contract and workspace plan.

Non-goals

• Provider SDKs or task interpretation in Grove core.
• Automatically guessing cross-repo dependencies without an explicit preset/blueprint.
• Implementing or supervising a coding-agent runtime inside gw-grab; optional handoff composes Grove 1.2: Containerized agent workspaces and handoff #64.
• Opening PRs or coordinating merge order in the MVP.
• Supporting every URL provider before validating the GitHub flow.

Dependencies

• Epic: Make workspace operations transactional and recoverable #59 should establish trustworthy lifecycle, rollback, and recovery semantics before this becomes a promoted automation path.
• Epic: Replace MCP with an agent-native CLI #63 should establish the stable agent-native CLI contract that gw-grab composes instead of private state or duplicated orchestration.
• Grove 1.2: Containerized agent workspaces and handoff #64 provides the optional containerized --agent handoff after task/workspace resolution.