refit

Files (1)

• SKILL.md

SKILL.md (first lines)

# Refit a Workflow

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.

---

## Phase 1: Discovery

### Step 1 — Identify the workflow

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).

### Step 2 — Read current scaffolding and extract version stamps

Read each scaffolding file and extract its version stamp:

1. **README** — Read `{dir}/README.md`. Extract version from YAML frontmatter `commissioned-by: spacedock@X.Y.Z`. Store as `{readme_version}`.
2. **Mod files** — Scan `{dir}/_mods/*.md` for installed mods. For each, read the `version` frontmatter field. Match against canonical mods at `{project_root}/mods/{name}.md` by filename. Store the local version and canonical version for each. Also scan `{project_root}/mods/*.md` for mods not yet installed.
3. **Legacy status script** — If `{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.

### Step 3 — Read current Spacedock version

Read `.codex-plugin/plugin.json` from the Spacedock plugin directory (the directory containing the `skills/` folder — resolve from your own plugin context). The `.claude-plugin/plugin.json` mirror carries the same `version` for the Claude host. Extract the `version` field and store it as `{current_version}`.

### Step 4 — Evaluate

- If all version stamps match `{current_version}`: report "Workflow is already up to date." and stop.
- If no stamps were found on any versioned file (README): enter **Degraded Mode** (see below).
- Otherwise: proceed to Phase 2 with the list of outdated files.

---

## Phase 2: Classify Files by Upgrade Strategy

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.

---

## Phase 3: Execute Upgrades

### Extract workflow-specific values from README

Before generating any files, read `{dir}/README.md` and extract:

1. **Mission** — from the `# {title}` heading (first H1).
2. **Stages** — from the `## Stages` section. Each `### \`{stage_name}\`` subsection is a stage, in order. For each stage, extract:
   - Stage name
   - Inputs, Outputs, Good, Bad descriptions
   - Whether "Human approval: Yes" appears (indicates an approval gate for the transition INTO this stage)
3. **Schema fields** — from the `## Schema` section's YAML block.
4. **Entity description** — from the first paragraph after the H1.

### 3a. Legacy Status Script (Remove)

If `{dir}/status` exists, it's a legacy workflow-local status script. The status viewer now ships as the `spacedock status` launcher command.

1. Inform the captain: "The status viewer is now the `spacedock status` launcher command. Removing the workflow-local `{dir}/status` script."
2. `git rm {dir}/status`

### 3b. README (Show Diff)

1. Re-select the matching template for this workflow's shape (development / experiment / refinement) and generate its FULL body for this workflow, substituting the extracted values (mission, stages, schema). Regenerate the workflow-INDEPENDENT sections too — `## Workflow-specific rules`, the proof/triage bullets, and the `## {Entity} Template` / `Verified by` example — not only the stage prose. These carry the accumulated scaffolding content; a refit that re-renders only the stage values propagates the version stamp but not the content the template gained since this workflow was commissioned.
2. Diff it against the user's current README.
3. Present the diff to the captain, noting which differences are likely template changes vs user customizations:

> **README 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.
>
> Additive sections the current template gained since your workflow was commissioned (new proof/triage bullets, a fixed example) appear as additions in this diff — those are the accumulated scaffolding content, safe to adopt; hunks that touch your customized stage prose are yours to judge.

Do NOT auto-modify the README. The captain decides what to adopt.

### 3c. Mods (Version diff)

For each mod file in `{dir}/_mods/*.md`:

1. **Match against canonical** — Check if `{project_root}/mods/{name}.md` exists (matching by filename).

2. **If canonical exists** — Compare the `version` frontmatter field in the local file against the canonical file.
   - If versions match: report "up to date" and skip.
   - If versions differ: show a diff between the local and canonical files. Ask the captain:

> **Mod update: {name}** (local: {local_version} → canonical: {canonical_version})
> {diff output}

From spacedock-dev/spacedock, Apache-2.0.

More from spacedock-dev/spacedock