/workspace-setup

name: workspace-setup
description: Create or deliberately adopt a multi-repository Docflow WORKSPACE with a registry and portable memory. Use for workspace-setup or establishing a workspace home. NOT for bootstrapping a member repository, orientation, planning an outcome or executing assignments.

workspace-setup

Establish the operator-selected canonical workspace home.

Operating contract

**Inputs:** selected destination, new/adopt choice, purpose, canonical home, member identities/paths, owner, native host and write scope. **Effects:** create or merge only the agreed workspace files and ignores; initialise its Git history only when authorised. Cloning/registering members is a separate named effect. Never implicitly convert a parent container. **Native claims / dependencies / resources:** confirm ownership of the destination and any shared configuration; require explicit member access before registration validation. No member execution is assigned. **Stopping point:** a validated, inspectable workspace with a dated overview, or a concrete missing-input/asset/ownership blocker. **Receipt:** paths created/merged, preserved files, package revision, actual validation command/output/exit, unresolved members, host availability and next action. Do not create a fictitious run for setup without a work/grant.

Resolve inputs and current authority

Reuse applicable choices already supplied, including host, actor, paths, scope, depth and stopping point. Summarise the resolved choices; ask only for a material missing or conflicting choice. A recorded preference alone does not supply authority. Selection sets priority; accepted agreement, role, profile, registry membership and a copied brief grant no execution.

Locate the installed sibling bootstrap skill (resolve symlinks first). Its `templates/workspace-assets.json` lists the packaged asset locations: `../../workspace` in a plugin or `../../docflow-workspace` in a detached copy, relative to bootstrap. An explicit asset root is valid. Read that root's `CONTRACT.md`, `schema.json` and `README.md`; all templates are in bootstrap's `templates/`. If missing, report the exact missing asset and stop dependent writes. Never assume a source checkout or install/fetch dependencies implicitly. The external validator requires Node.js 22+.

For adoption, read the existing workspace entry point, registry, conventions and canonical records. For a new home, inspect only files already present; missing initial workspace files are expected and will be created from the authorised setup choices. Read declared native member instructions when members are supplied and member access is authorised. Resolve canonical home/full UUID and contained paths, including symlinks; a missing member stays registered with diagnostics. Search only authorised roots. Copied context and search indexes are discovery aids: read current authority, claims and critical constraints directly.

Before each dependent action, recheck the actual operator mandate for actor, scope, effects, conditions and stopping point. Initial authorised setup, scoped reads and authorised canonical planning use that mandate; they do not require or justify inventing a work record or execution grant. For grant-bound native execution, additionally recheck the current grant: actor, scope revision, delivery, action/effects, conditions, start, expiry, revocation/suspension, exact grant revision and stopping point. Reuse an existing compatible grant; request only missing or changed authority. Check native ownership, dependencies and shared resources separately. Reference-only members permit only scoped non-mutating actions. A denied tool/action stops that action across alternate tools, routes and delegates. Contact loss is not worker exit and never permits reassignment.

Validate with `node <assets>/validate.mjs <workspace> --at <current-UTC>`; supply the actual UTC time and retain complete output/exit. Validation checks record consistency, not permission, live ownership or proof of execution. Unknown, stale, skipped, missing and failed evidence remain distinct.

Procedure

1. Inspect the selected destination and existing Git/ignore/instruction files. For adoption, describe the exact preservation/merge plan using supplied approval. Never replace existing content or initialise the surrounding container. Recheck permission for each write. 2. Follow the asset README's assembly mapping: workspace README and AGENTS at the root, registry/conventions/index under `.docflow_workspace/`. Create the five record folders plus agents, profiles, integrations and ignored local state. Ignore `/repos/` and `/.docflow_workspace/local/` without dropping existing ignore rules. Members retain independent Git histories, never submodules or copied governance. 3. Replace synthetic home/owner/paths with actual choices. Start with empty records and `{"schema":1,"sources":[]}`; register only supplied member identities, aliases, paths, role and native instructions. No remote fetch or clone follows merely from registry membership. A member may be remote-only: `role: reference`, a `remote` URL and no path or instructions; its references are identity-only and its actions stay non-mutating. Register a derived documentation set in `sources.yaml` `documents` by external locator and digest; never vendor the document into the workspace. 4. Copy the five workspace record forms to the adopter's `.docflow_workspace/templates/`, outside canonical record folders. Offer the four `workspace-role-*.md` starter forms, profile examples and source catalogue from bootstrap. The separate `workspace-run-import.md` form backfills imported execution history read-only; it carries no grant and never satisfies a dispatch check. Adopt only chosen entries, pin actual installed revisions and owner, and preserve existing configuration. Empty recommendations and no extra role/tool are valid choices.