Epic: Blueprints — presets as code (Preset 2.0)

[nicksong-z]

Framing: Preset 2.0

Blueprints are presets as code: the natural evolution of Grove's existing presets from personal repository lists into portable, version-controlled workspace definitions.

Preset today	Blueprint / Preset 2.0
Local to one user	Version-controlled and shareable
Repositories identified by folder name	Repositories identified by canonical remote
Repository list only	Repos, branches, setup, preparation, and metadata
Stored in ~/.grove/config.toml	Local file or pinned remote Git source
Machine-specific	Portable across a team
Creates a workspace	Can plan, apply, validate, and prebuild it

Use Blueprint as the durable feature/schema name and Preset 2.0 as the migration and product explanation.

Blueprints are portable, version-controlled presets that define a complete Grove workspace.

Problem

Grove presets are useful but personal and machine-local: they live in ~/.grove/config.toml and identify repositories by local folder name. A teammate cannot check out a project and reproduce the same multi-repo workspace without manually recreating that configuration.

Per-repo .grove.toml files describe individual repositories, but there is no shareable declaration of:

• which repositories belong together;
• how they should be resolved and branched;
• which setup is required after assembly; or
• where a team-maintained workspace definition comes from.

Goal

Introduce a small, versioned workspace blueprint that can be committed, shared, reviewed, loaded from a pinned Git source, and applied on another machine:

gw plan  -f grove.workspace.toml -b feat/login --format json
gw apply -f grove.workspace.toml -b feat/login --format json

Or through a familiar local preset alias:

gw create -p backend -b feat/login

A blueprint should make a polyrepo workspace reproducible without turning Grove into a monorepo tool, general build system, or cloud environment platform.

Proposed v1 format

Illustrative only; finalize through contract/schema review:

version = 1
name = "backend"

[[repos]]
name = "api"
remote = "https://github.com/acme/api.git"
base_branch = "main"

[repos.setup]
run = "go mod download"
timeout = "5m"

[[repos]]
name = "web"
remote = "https://github.com/acme/web.git"
base_branch = "main"

[repos.setup]
run = "pnpm install --frozen-lockfile"
timeout = "10m"

[[repos]]
name = "worker"
remote = "https://github.com/acme/worker.git"
base_branch = "stage"
optional = true

[[setup]]
name = "Generate shared configuration"
run = "./scripts/configure-workspace.sh"
cwd = "."
timeout = "2m"

Key properties:

• Repositories use canonical remote identity, not machine-specific folder names.
• The workspace branch/source is supplied by CLI or a source resolver such as gw grab; it is not normally hard-coded into a reusable blueprint.
• Repo-level setup runs in that repo's new worktree.
• Top-level setup runs from the assembled workspace after required repos exist.
• Existing per-repo .grove.toml remains supported; the schema must define one explicit execution/precedence order and avoid silently duplicating setup.
• Existing hook metadata (timeout, stream, on_failure) should be reused where it fits.
• Local path resolution and clones use the existing repo_dirs configuration.
• Setup commands are visible in plan and require approval when loaded from new or changed remote content.
• Secrets are never stored in a blueprint.

Preset compatibility and migration

Current presets remain valid local shortcuts. Blueprints extend rather than break them.

Suggested composition:

# ~/.grove/config.toml
[presets.backend]
blueprint = "git::https://github.com/acme/workspaces.git//backend.toml?ref=v1.2.0"

Suggested migration helpers:

gw preset export backend > grove.workspace.toml
gw preset add backend --blueprint <source>

Compatibility requirements:

• gw create -p <existing-preset> keeps working unchanged.
• A preset may reference either its current local repo list or one blueprint source, with unambiguous validation.
• Exporting a current preset produces a valid local blueprint without mutating the preset.
• Remote source resolution is recorded in workspace state for diagnostics and reproducibility.

Blueprint sources

Local

gw plan -f ./grove.workspace.toml -b feat/login

Remote Git

gw plan 'git::https://github.com/acme/workspaces.git//backend.toml?ref=v1.2.0' \
  -b feat/login

Git is the first remote source because it already provides authentication, history, review, diffs, and immutable commit references.

Requirements:

• resolve tags/branches to a concrete commit and record it;
• support an explicit digest/lock representation for unattended use;
• cache resolved manifests locally without silently changing their identity;
• re-prompt for setup approval when resolved content or commands change;
• show source, resolved revision, and digest in human and JSON plans.

S3 or other source types should use a backend/plugin contract later, after remote Git demonstrates real demand. Binary Oven artifacts belong in OCI/S3, not Git; see #62.

User flow

Plan

gw plan -f grove.workspace.toml -b feat/login

Produces a deterministic, non-mutating plan:

Workspace: feat-login
Branch:    feat/login
Blueprint: backend @ sha256:...

api        found at ~/dev/api        create from origin/main
web        missing locally           clone, then create from origin/main
worker     optional                   skip

Setup:
  api      go mod download
  web      pnpm install --frozen-lockfile
  root     ./scripts/configure-workspace.sh

Apply

gw apply -f grove.workspace.toml -b feat/login

Executes the reviewed plan through the same trustworthy workspace service used by gw create.

Delivery slices

1. Local blueprint

• Write a schema/design document with versioning and compatibility rules.
• Parse and validate version = 1 local blueprints.
• Resolve repositories by normalized canonical remote identity.
• Support required/optional repos, base branches, repo setup, and workspace setup.
• Show human and agent-native plans without mutation.
• Apply transactionally through Epic: Make workspace operations transactional and recoverable #59.

2. Preset 2.0 compatibility

• Keep current repo-list presets backwards compatible.
• Add preset export to a local blueprint.
• Allow a local preset to reference a blueprint source.
• Document presets as shortcuts and blueprints as portable definitions.

3. Remote Git blueprints

• Resolve a manifest from a Git URL/path/ref.
• Pin and persist resolved revision/content digest.
• Add content-based setup approvals and safe local caching.
• Provide clear offline, authentication, stale-cache, and changed-content errors.

Acceptance criteria

• Two developers with different local folder layouts can apply the same blueprint and receive equivalent workspaces.
• gw plan performs no filesystem, Git, state, or setup mutations.
• Invalid/unsupported schema versions fail before any mutation.
• Missing required repositories are clearly planned and can be cloned during apply.
• Ambiguous remote matches never select a repository silently.
• All setup commands and execution directories are visible before apply.
• Changed remote setup commands invalidate prior approval.
• gw apply uses the transactional/recovery guarantees established by Epic: Make workspace operations transactional and recoverable #59.
• Human and agent-native JSON plans are covered by unit and e2e tests.
• Existing presets and .grove.toml remain backwards compatible.

Follow-up possibilities

Only after the core Preset 2.0 workflow is useful:

• gw ready health/validation checks across all repositories.
• Preparation/cache declarations consumed by Grove Oven (Epic: Grove Oven — maintain ready-to-claim hot workspaces #62).
• A generated lock/snapshot file recording resolved repos and commit/base refs.
• gw grab selecting a blueprint for a task.
• S3/OCI/HTTP source resolver plugins where appropriate.

Non-goals

• Secrets in blueprint files.
• A general task runner or replacement for Make, just, Nx, or CI.
• Container/sandbox provisioning in v1.
• Automatic dependency-graph inference.
• Cloud synchronization or a hosted blueprint registry.
• Plugin installation or arbitrary executable download as a side effect of gw apply.
• YAML, inheritance, overlays, or a templating language in the first schema.
• Native S3 support before remote Git is validated.

Dependencies

• Epic: Make workspace operations transactional and recoverable #59 — trustworthy transactional operations and recovery.
• Epic: Replace MCP with an agent-native CLI #63 — stable agent-native plan/apply and machine-output contracts.
• Epic: Turn a task or PR URL into a ready workspace with gw grab #60 — informs how source-derived branch/provenance composes with reusable blueprints.
• Epic: Grove Oven — maintain ready-to-claim hot workspaces #62 — consumes blueprint preparation metadata after the base schema is stable.