setup-runstore

name	setup-runstore
description	One-time setup of a persistent archive for all simulation runs across workspaces and templates. Use when the user wants to "set up a runs archive", "configure where runs are stored", or asks where their forecasts are kept. Creates the runstore directory, persists the path via the plugin-data-storage convention so it survives plugin updates, and registers existing workspaces.
allowed-tools	Bash, Read, Write, Edit, Glob

Set up the runs archive

Without this, runs live scattered inside each workspace's reports/ dir. With it, every run across every template is archived in one place — making grade-run aggregate stats meaningful, and making bundling / browsing / cross-run comparison possible.

Inputs to gather

1. Runstore root path — where the archive should live. Default: ~/geopol-runs/. Suggest somewhere under ~/Documents/ or ~/repos/ (this is user-owned data, not plugin-owned — it shouldn't live under ~/.claude/).
2. Mirror mode — symlink (default, zero-copy) or copy (snapshot at registration time). Symlink is right for almost everyone; copy is for users who want the archive to be fully portable.

Steps

1. Resolve the plugin data dir with the standard pattern:

   PLUGIN_DATA="${CLAUDE_USER_DATA:-${XDG_DATA_HOME:-$HOME/.local/share}/claude-plugins}/geopol-sim"
   mkdir -p "$PLUGIN_DATA"
   

2. Create the runstore. mkdir -p <runstore_root>/{by-date,by-template,by-workspace}. These are organisational views — actual run dirs live under by-date/YYYY/MM/DD/<workspace>-<run-id>/ and are reachable via symlinks from the other two views.
3. Persist the config. Write <PLUGIN_DATA>/config.json:

   {
     "runstore_root": "<absolute path>",
     "mirror_mode": "symlink",
     "registered_workspaces": []
   }
   

4. Discover existing workspaces. Glob ~/repos/**/.template-id (depth-limited) for any pre-existing scaffolded workspaces. Ask the user which (if any) to register.
5. Register each workspace. For every existing run dir under <workspace>/reports/<run-id>/, link it into the runstore:

   ln -s <workspace>/reports/<run-id> <runstore_root>/by-date/<YYYY>/<MM>/<DD>/<workspace-slug>-<run-id>
   ln -s <workspace>/reports/<run-id> <runstore_root>/by-template/<template-id>/<workspace-slug>-<run-id>
   ln -s <workspace>/reports/<run-id> <runstore_root>/by-workspace/<workspace-slug>/<run-id>
   

   Append the workspace path to registered_workspaces in the config.
6. Report back. Runstore root, count of workspaces / runs registered, where to look in future.

Going forward

After setup, scaffold-simulation will register new workspaces automatically, and run-simulation should link new run dirs into the store on completion (extension to that skill — when the runstore exists, it links; when it doesn't, it just leaves runs in <workspace>/reports/).

Notes

• The runstore is user-owned data, deliberately NOT under $CLAUDE_USER_DATA. The config under $CLAUDE_USER_DATA only stores the pointer to the runstore.
• Symlinks mean past runs follow the workspace if it moves — if a workspace dir is renamed or deleted, the symlinks become dangling. update-templates could grow a lint pass for this; for v1 just warn the user.
• Don't auto-register every glob hit — confirm with the user.