gabrie30/ghorg/ghorg-create-vscode-generic-workspace

Create ghorg generic workspace

A generic workspace is a ghorg reclone entry that acts as a template. Every run of ghorg reclone <PREFIX>-generic-workspace clones the same repositories into a staging directory, then a post_exec_script asks for a name and renames the directory to <PREFIX>-<name>. Each run produces a new, independent workspace (one per feature, investigation, or task).

This differs from the ghorg-create-vscode-workspace skill, which creates one fixed workspace that is updated in place on each reclone.

Prerequisites

• ghorg must be installed and on the system PATH.
• Network access to the SCM provider (GitHub, GitLab, Bitbucket, etc.).
• bash and git must be available.

Platform support

macOS and Linux. The post-exec script is a bash script that ghorg executes directly, so on Windows it only works under WSL.

Environment variables

Stop with an error if HOME_DIR is empty or the user does not provide an SCM_ORG.

Paths

Workflow

Step 1: Resolve environment

Resolve HOME_DIR and SCM_ORG as described above.

Step 2: Ask for the prefix

Ask the user:

What prefix should workspaces created from this template use?

Example: payments produces workspaces like payments-fix-refunds.

Validation: Must match ^[a-z0-9-]+$. Ask again until valid. Store as PREFIX.

Step 3: Ask for repositories

Ask the user:

List the repositories to clone into every workspace, one per line.

Store as REPO_LIST. At least one repository is required.

Step 4: Ask for files to copy (optional)

Ask the user:

Are there local files to copy into every new workspace (for example `.env` files that are not in git)? Give one `source|destination` pair per line, or leave empty.

• source is an absolute path on this machine.
• destination is relative to the workspace root, usually <repo>/<path>.

Example: /path/to/my-app/.env|my-app/.env

Store as COPY_FILES. Empty is fine.

Step 5: Check for conflicts

Stop and report an error, without changing anything, if any of these already exist:

• A top-level key RECLONE_KEY in GHORG_RECLONE_CONFIG (grep -q '^<RECLONE_KEY>:' <GHORG_RECLONE_CONFIG>).
• The file REPO_FILE.
• The file POST_EXEC_SCRIPT.

Step 6: Create files

1. Create GHORG_CONFIG_DIR and BASE_DIR (with parents) if missing. Create an empty GHORG_RECLONE_CONFIG if missing.
2. Write REPO_FILE with REPO_LIST, one repository per line.
3. Copy TEMPLATE to POST_EXEC_SCRIPT and edit the copy:

• Replace __PREFIX__ with PREFIX.
• Replace __BASE_DIR__ with the absolute BASE_DIR.
• Add one quoted line per COPY_FILES entry inside COPY_FILES=( ), for example "/path/to/my-app/.env|my-app/.env".

1. Make it executable: chmod +x <POST_EXEC_SCRIPT>.
2. Check the syntax: bash -n <POST_EXEC_SCRIPT>.

Step 7: Append the reclone entry

Append to GHORG_RECLONE_CONFIG, replacing placeholders with resolved absolute values:

<PREFIX>-generic-workspace:
  cmd: "ghorg clone <SCM_ORG> --path=<BASE_DIR> --target-repos-path=<REPO_FILE> --output-dir=<PREFIX>-generic-workspace --stats-enabled=false"
  description: "Generic workspace for <PREFIX>. Each run creates a new <PREFIX>-<name> workspace"
  post_exec_script: "<POST_EXEC_SCRIPT>"

• Preserve all existing content. Add a newline first if the file does not end with one.
• Validate the file still parses: GHORG_RECLONE_PATH="<GHORG_RECLONE_CONFIG>" ghorg reclone --list > /dev/null. Discard the output because it can contain tokens.

Step 8: Create the first workspace (optional)

Ask the user whether to create a workspace now. If yes, ask for its name and run:

GHORG_RECLONE_PATH="<GHORG_RECLONE_CONFIG>" GENERIC_WORKSPACE_NAME="<name>" ghorg reclone <PREFIX>-generic-workspace

GENERIC_WORKSPACE_NAME skips the interactive prompt, which needs a terminal that agent shells do not have.

ghorg still exits 0 when the post-exec script fails. Treat the run as failed if the output contains ERROR: Running post_exec_script or the directory from the INFO: Workspace ready at line does not contain a <directory name>.code-workspace file, and show the post-exec logs section to the user.

If the name was already taken, the clone stays in BASE_DIR/<PREFIX>-generic-workspace and the next run reuses it. Ask for a different name and run the command again.

Step 9: Explain what was added

Tell the user the generic workspace was created, then explain what was added and how the pieces fit together, using this structure with resolved values. Include item 4 only if Step 8 created a workspace.

**What was added**
 
1.**Repo list:** `<REPO_FILE>`
   -Contains: the repositories cloned into every new workspace, one per line (<N> repos: <names>).
   -Role: ghorg reads it through `--target-repos-path`. Edit it to change which repos future workspaces get. Existing workspaces are not affected.
2.**Post-exec script:** `<POST_EXEC_SCRIPT>`
   -Contains: a bash script with its settings at the top: `PREFIX`, `BASE_DIR`, `OPEN_IN_VSCODE`, and `COPY_FILES` (<N> files: <destinations>, or none).
   -Role: ghorg runs it after every clone. It asks for a name, renames the fresh clone to `<PREFIX>-<name>`, adds the marker, root git repo, and `.code-workspace` file, copies `COPY_FILES`, and opens VS Code.
3.**Reclone entry:** `<PREFIX>-generic-workspace` in `<GHORG_RECLONE_CONFIG>`
   -Contains: the `ghorg clone` command (organization, `<BASE_DIR>`, repo list, and the `<PREFIX>-generic-workspace` staging folder) plus the path to the post-exec script.
   -Role: `ghorg reclone <PREFIX>-generic-workspace` runs it. Every run creates a new workspace.
4.**Workspace folder:** `<BASE_DIR>/<PREFIX>-<slug>/`
   -Contains: the cloned repos, any copied files, `<PREFIX>-<slug>.code-workspace`, a `.git` folder at the root, and the `.ghorg-generic-workspace` marker (prefix, reclone entry, creation time).
   -Role: where you work on this task. Open the `.code-workspace` file to load every repo in one window. The marker lets the cleanup skill identify the folder.
 
**Workflow:** run `ghorg reclone <PREFIX>-generic-workspace` and enter a name (`fix login bug` becomes `<PREFIX>-fix-login-bug`), then work in the new folder. Every run clones into a new folder, so existing workspaces are never reset or overwritten.
 
**Cleaning up later:** use the `ghorg-cleanup-vscode-generic-workspace` skill to delete old workspaces or remove this template. It shows what it will remove and asks before deleting.

How a run works

1. ghorg clones REPO_LIST into BASE_DIR/<PREFIX>-generic-workspace.
2. The post-exec script takes the name from GENERIC_WORKSPACE_NAME or prompts on the terminal, then slugifies it (My Fix! becomes my-fix).
3. It renames the staging directory to BASE_DIR/<PREFIX>-<slug> and aborts if that already exists.
4. It writes a .ghorg-generic-workspace marker, runs git init at the workspace root, creates <PREFIX>-<slug>.code-workspace, copies COPY_FILES, and opens the workspace in VS Code when it can find it.

To change copied files or stop VS Code from opening, edit COPY_FILES or OPEN_IN_VSCODE in POST_EXEC_SCRIPT.

VS Code workspace file

Every workspace gets a VS Code workspace file in its root, named after the workspace folder:

BASE_DIR/<PREFIX>-<slug>/<PREFIX>-<slug>.code-workspace

Example: HOME_DIR/workspaces/payments-fix-refunds/payments-fix-refunds.code-workspace

With the following contents:

{
   "folders": [
      {
         "path": "."
      }
   ],
   "settings": {}
}

The post-exec script writes this file on every run and overwrites any existing one. The content comes from the heredoc in post-exec-template.sh, so keep the two in sync when editing either.

Failure conditions

Stop and report an error. Never silently continue when:

• HOME_DIR or SCM_ORG cannot be resolved.
• RECLONE_KEY, REPO_FILE, or POST_EXEC_SCRIPT already exists.
• A file or directory cannot be written, or bash -n fails.
• GHORG_RECLONE_CONFIG no longer parses after appending.
• ghorg reclone fails in Step 8 (non-zero exit, or a post-exec error as described there).