Help us improve
Share bugs, ideas, or general feedback.
From spacedock
Upgrades an existing workflow's scaffolding files (README, mods) to match the current Spacedock version, with optional entity frontmatter migration.
npx claudepluginhub clkao/spacedock --plugin spacedockHow this skill is triggered — by the user, by Claude, or both
Slash command
/spacedock:refitThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
You are refitting (upgrading) an existing workflow to match the current Spacedock version. This covers scaffolding files (README, mods) and, when schema changes require it, migrating entity frontmatter data. Agent files and the status viewer are shipped with the Spacedock plugin and do not need local updates.
Migrates DIA projects between versions (v1->v2->v3): runs migration scripts, renames IDs, flattens analysis, regenerates BACKLOG.md. Idempotent. For brownfield projects use /reverse-engineering.
Autonomously plans and executes migrations (framework upgrades, API bumps, deprecation removal) with phased plans, blast radius mapping, and per-phase verification.
Provides structured workflow packs for 7 common Claude Code tasks: codebase exploration, bug fixing, safe refactoring, TDD, repo review before merge, CLAUDE.md generation, and migration planning.
Share bugs, ideas, or general feedback.
You are refitting (upgrading) an existing workflow to match the current Spacedock version. This covers scaffolding files (README, mods) and, when schema changes require it, migrating entity frontmatter data. Agent files and the status viewer are shipped with the Spacedock plugin and do not need local updates.
Follow these five phases in order. Do not skip or combine phases.
The user must provide a workflow directory path. If they didn't, ask:
Which workflow directory should I refit?
Store the confirmed path as {dir}. Resolve it to an absolute path. Also derive {project_root} (git root or cwd) and {dir_basename} (last path component).
Read each scaffolding file and extract its version stamp:
{dir}/README.md. Extract version from YAML frontmatter commissioned-by: spacedock@X.Y.Z. Store as {readme_version}.{dir}/_mods/*.md for installed mods. For each, read the version frontmatter field. Match against canonical mods at {spacedock_plugin_dir}/mods/{name}.md by filename. Store the local version and canonical version for each. Also scan {spacedock_plugin_dir}/mods/*.md for mods not yet installed.{dir}/status exists, note it for cleanup (status now ships with the plugin).If a file doesn't exist, note it as missing and skip it.
Read .codex-plugin/plugin.json from the Spacedock plugin directory (the directory containing the skills/ folder — resolve from your own plugin context). Treat .agents/plugins/marketplace.json as the authoritative local marketplace surface and .claude-plugin/* as synchronized legacy mirrors. Extract the version field from .codex-plugin/plugin.json and store it as {current_version}.
{current_version}: report "Workflow is already up to date." and stop.Each scaffolding file gets a specific upgrade strategy based on how safe it is to auto-replace:
| File | Strategy | Rationale |
|---|---|---|
README.md | Show diff | Users customize stages, schema fields, quality criteria. Too risky to auto-replace. Show what the current template would produce and let the captain decide. |
_mods/{name}.md | Version diff | Compare version frontmatter against canonical. Show diff if changed, ask for confirmation. |
status (legacy) | Remove | Status viewer now ships with the plugin. Remove the workflow-local copy if present. |
Present the classification to the captain:
Upgrade plan:
File Current State Strategy status{status_version or "no stamp"} Replace README.md{readme_version or "no stamp"} Show diff (manual review) _mods/{name}.md(for each){local_version vs canonical_version / custom mod} Version diff Proceed with this upgrade plan? (y/n)
For mods, include all files found in _mods/.
Wait for the captain to confirm before proceeding.
Before generating any files, read {dir}/README.md and extract:
# {title} heading (first H1).## Stages section. Each ### \{stage_name}`` subsection is a stage, in order. For each stage, extract:
## Schema section's YAML block.If {dir}/status exists, it's a legacy workflow-local status script. The status viewer now ships with the Spacedock plugin at skills/commission/bin/status.
{dir}/status script."git rm {dir}/statusREADME template diff:
The following differences exist between your README and what the current template would generate. Differences may be template improvements or your intentional customizations.
{diff output}
I have NOT modified your README. Review the diff and apply any changes you want manually, or tell me which specific changes to make.
Do NOT auto-modify the README. The captain decides what to adopt.
For each mod file in {dir}/_mods/*.md:
Match against canonical — Check if {spacedock_plugin_dir}/mods/{name}.md exists (matching by filename).
If canonical exists — Compare the version frontmatter field in the local file against the canonical file.
Mod update: {name} (local: {local_version} → canonical: {canonical_version}) {diff output}
Update this mod? (y/n)
Found custom mod: {name} — {description from frontmatter}. No canonical version to compare against. No action needed.
{spacedock_plugin_dir}/mods/*.md not present in {dir}/_mods/, offer to install:New mod available: {name} — {description from frontmatter}. Install it? (y/n)
If accepted, copy the canonical file to {dir}/_mods/{name}.md. Create _mods/ if it doesn't exist.
If {project_root}/.claude/agents/pr-lieutenant.md exists and {dir}/_mods/pr-merge.md does not, offer migration:
Migration: pr-lieutenant → pr-merge mod
Your workflow uses a pr-lieutenant agent for PR management. Spacedock now uses mods instead. I'll:
- Create
{dir}/_mods/pr-merge.mdwith the PR management mod- Remove
agent: pr-lieutenantfrom any README stage entries- Regenerate the first-officer with mod discovery
The pr-lieutenant agent file at
.claude/agents/pr-lieutenant.mdwill be left in place. You can delete it manually if no longer needed.Proceed with pr-lieutenant migration? (y/n)
If accepted:
{spacedock_plugin_dir}/mods/pr-merge.md to {dir}/_mods/pr-merge.mdagent: pr-lieutenant from any stage entriesAfter upgrading scaffolding, check whether schema changes require migrating existing entity data.
README frontmatter may contain id-style: sequential, id-style: sd-b32, or id-style: slug. Refit must preserve the current id-style; do not silently change it. Report the current style in the refit summary, recommend sd-b32 only when collaboration pressure exists (worktree stages, PR/merge mods, multiple creators, branches, or offline work), and require explicit captain approval before changing README frontmatter.
Before any approved style change, run status --validate against the workflow and report failures. Existing sequential workflows require no data rewrite. SD-B32 means Spacedock Base32: this style requires each entity to store a 24-character lowercase SD-B32 stored ID derived from SHA-256 digest material and formatted with Spacedock's alphabet 0123456789abcdefghjkmnpqrstvwxyz, while status displays shortest unique prefixes. Slug style derives identity from filenames and makes status --next-id non-applicable. Migration is manual migration in this release: use validation to make the change safe, and defer rewrite automation or bulk frontmatter rewriting to a separate tracked task.
Compare the old README's ## Schema and ### Field Reference sections against the new version. Look for:
priority → score)If no schema changes affect entity data, skip to Phase 5.
For each detected schema change, scan all entity files in {dir}/*.md (excluding README.md) and identify which entities have values in the affected fields.
Present findings to the captain:
Schema migration needed:
{description of what changed in the schema}
Affected entities: {list of entities with current values that need migration}
Proposed migration: {what the migration would do — e.g., "Convert score from /25 to 0.0–1.0 by dividing by 25"}
Apply this migration? (y/n)
On the captain's approval, update the affected entity frontmatter fields. Use the Edit tool — never rewrite whole entity files. Only touch the specific fields identified in the migration plan.
Show a summary of what was migrated:
Migrated {N} entities: {list of entity: old_value → new_value}
{current_version} in the README YAML frontmatter: commissioned-by: spacedock@{current_version}.Refit complete:
File Action status{Removed (legacy) / Not present} _mods/{name}.md(for each){Updated / Already current / Installed / Custom (no action)} README.md{Stamp updated / User-reviewed / No changes} Suggest committing:
git commit -m "refit: upgrade workflow scaffolding to spacedock@{current_version}"
When no version stamps are found on the README, the original baseline cannot be determined. Inform the captain and offer two options:
No version stamps found. This workflow was commissioned before version stamping was implemented, or the stamps were removed. I can't determine what the original scaffolding looked like.
Two options:
- Stamp only — Add version stamps to existing files without changing anything else. This establishes a baseline for future refits.
- Full refit with review — Generate what the current templates would produce and show a full diff for every scaffolding file. You review and approve each change.
Which option?
Add version stamps to versioned files without modifying anything else:
commissioned-by: spacedock@{current_version} (wrap in --- delimiters if frontmatter doesn't exist).# commissioned-by: spacedock@{current_version} as the second line (after #!/bin/bash).Execute Phase 3, but show a full diff for every file (including status) and require the captain's explicit approval before replacing each one. Never auto-replace files without a version stamp — the risk of overwriting customizations is too high.
git diff or git checkout to recover.