forge-orkes 0.31.0 → 0.33.0

package/bin/create-forge.js

@@ -37,6 +37,16 @@ const FRAMEWORK_OWNED_DIRS = ['.claude/agents', '.claude/skills'];
 // Experimental / opt-in skills installed separately (e.g. from experimental/m10).
 // They are NOT in the shipped base template, so the framework-owned auto-clean
 // would otherwise delete them on upgrade. Preserve them instead.
+//
+// The npm tarball ships only bin/ + template/ — NOT experimental/ — so this route
+// cannot diff or re-sync an experimental skill against its source. Preserving
+// blindly is what silently froze them pre-0.33.0 (issue #5): a base migration that
+// changed experimental-skill behavior became a no-op. The structural fix lives
+// elsewhere — (a) the clone-based `upgrading` skill (Step 3b) offers a real
+// re-sync against experimental/*/source, and (b) load-bearing conventions are
+// promoted to base (FORGE.md) so they no longer depend on the frozen skill. Here
+// we can only PRESERVE + flag, so the report below tells the user staleness was
+// not checked and how to refresh.
 const EXPERIMENTAL_SKILL_PATHS = ['.claude/skills/orchestrating'];
 
 function isExperimentalSkillPath(displayPath) {
@@ -623,8 +633,17 @@ async function upgrade() {
   if (results.preserved.length > 0) {
     console.log(`  Preserved (${results.preserved.length}):`);
     for (const f of results.preserved) {
-      console.log(`    ${f} (kept — opt-in experimental skill)`);
+      console.log(`    ${f} (kept — opt-in experimental skill; staleness not checked by npm)`);
     }
+    console.log(
+      `    ↳ The npm upgrade does not ship experimental sources, so it cannot`
+    );
+    console.log(
+      `      re-sync these. To refresh against a Forge clone, run the \`upgrading\``
+    );
+    console.log(
+      `      skill (offers a re-sync), or re-run \`experimental/<pkg>/install.sh\`.`
+    );
     console.log();
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.31.0",
+  "version": "0.33.0",
   "description": "Set up the Forge meta-prompting framework for Claude Code in your project",
   "bin": {
     "create-forge": "./bin/create-forge.js"

package/template/.claude/skills/chief-of-staff/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: chief-of-staff
+description: "Coordinate multiple active Forge streams. Use for explicit stream intents, mid-flow pivots, delegated work, cross-stream conflict checks, and merge ordering."
+---
+
+# Chief Of Staff
+
+Project-level traffic control for concurrent Forge work. The Chief owns the
+project stream registry, stream lifecycle, conflict checks, context switching,
+delegation, merge order, and closeout.
+
+Use this skill when the user explicitly asks about streams, Chief of Staff, or
+parallel application work. Do not route ordinary single-feature work here by
+default. Inside each stream, continue to use Forge's Quick, Standard, and Full
+tiers for actual execution.
+
+## Operating Model
+
+Forge has three coordination layers:
+
+| Layer | Owner | Purpose | Default context |
+|-------|-------|---------|-----------------|
+| Project | Project Chief | Active streams, conflicts, pivots, merge order | `.forge/streams/active.yml` |
+| Stream | Stream Chief or lead session | One coherent line of application work | `.forge/streams/{stream}.yml` + `brief.md` |
+| Work Package | Worker session | Delegated bounded task | `.forge/streams/{stream}/packages/{id}.yml` |
+
+Workers never coordinate laterally. A worker reports to its stream chief or the
+Project Chief. Scope expansion, shared-surface edits, and cross-stream conflict
+questions return to the Chief before work continues.
+
+## Stream States
+
+- `draft` - described but not ready for active work
+- `active` - currently being driven in this session
+- `paused` - safe to resume later; context snapshot is current
+- `delegated` - worker session or external session is carrying the stream
+- `blocked` - cannot proceed until a dependency, decision, or conflict clears
+- `ready` - implementation is ready for merge or verification
+- `merged` - stream work has landed in the integration branch
+- `closed` - final outcome recorded; no active coordination remains
+
+## Context Loading
+
+1. Read `.forge/streams/active.yml` first.
+2. If missing, create it from `.forge/templates/streams/active.yml`.
+3. Load only the selected stream's `.forge/streams/{stream}.yml`.
+4. Load the selected stream's `brief.md` when the user needs status, handoff,
+   conflict context, or resume context.
+5. Load work packages only when delegating, checking worker status, or closing
+   a stream.
+
+Keep summaries in the registry short. Deep history belongs in stream briefs,
+packages, plans, verification reports, commits, and archived artifacts.
+
+## Supported Intents
+
+| Intent | Examples | Action |
+|--------|----------|--------|
+| Show | "show streams", "active streams", "what is running?" | Run Registry Drift Check, then summarize registry without loading all deep history |
+| Start | "start stream X", "new stream for billing" | Snapshot current stream, create stream files, register stream |
+| Pause | "pause stream X" | Update brief, mark paused, keep next action explicit |
+| Resume | "resume stream X" | Load stream context, set active, surface blockers and ownership |
+| Delegate | "delegate stream X", "farm this out" | Create or update a work package and handoff prompt |
+| Adopt M10 | "adopt existing M10 worktrees", "migrate active orchestrating sessions" | Wrap live M10 worktrees as streams without teardown |
+| Sync | "sync streams" | Run Registry Drift Check, then refresh registry summaries from active stream briefs |
+| Detect Conflicts | "detect conflicts", "check stream conflicts" | Compare ownership and dependencies |
+| Merge Safe | "merge safe?", "what can land?" | Identify ready streams with no blocking conflicts |
+| Close | "close stream X" | Record final status, archive/mark closed, clear active pointer if needed |
+
+## Registry Drift Check
+
+Forge keeps two registries that both describe "what work is active," with no
+automatic reconciliation: `.forge/state/index.yml` (milestones, owned by the
+`forge` skill) and `.forge/streams/active.yml` (streams, owned by the Chief).
+`/forge` and `/chief-of-staff` can therefore present different pictures of the
+project. Run this check at the **start of the Show and Sync intents** so the
+divergence is surfaced instead of silently left to the operator.
+
+This is **advisory — it never blocks, never auto-creates a milestone, and never
+auto-writes a stream.** It reports, and offers.
+
+1. Read active milestones from `.forge/state/index.yml` (those with
+   `status: active`). If the file is absent, skip the check silently — a
+   streams-only project has nothing to reconcile.
+   - Note: invoking `/chief-of-staff` directly bypasses `forge`'s boot preflight,
+     so `index.yml` may be stale (it is regenerated by `forge`'s Rollup, not by
+     the Chief). Read it as-is; do not run Rollup from the Chief. If it looks
+     stale, say so and suggest a `/forge` pass.
+2. Read the stream registry from `.forge/streams/active.yml`.
+3. Map each active milestone to a stream by id, trying these forms in order:
+   `m-{id}`, `milestone-{id}`, bare `{id}`, and any stream whose
+   `context.milestone` points at `.forge/state/milestone-{id}.yml`.
+4. Report each mismatch:
+   - **Active milestone with no stream** → offer to add it as a `paused` stream
+     (do not create it automatically). Quick-fix milestones legitimately may not
+     warrant a stream — let the operator decide.
+   - **Stream pointing at a `deferred`, `complete`, or absent milestone** → the
+     stream's status should follow its milestone; offer to update it (pause a
+     stream whose milestone deferred, close one whose milestone completed).
+   - **Stream with no milestone counterpart** → informational only. Quick-fix
+     streams are valid; never auto-create a milestone for them.
+5. If everything maps cleanly, say so in one line (`registries aligned`) and
+   continue to the intent.
+
+Keep the output compact — a few lines under a `Registry drift:` header, then
+proceed with the requested Show/Sync.
+
+## Start Stream Flow
+
+1. Read the registry.
+2. If another stream is active, snapshot its current state:
+   - update `.forge/streams/{stream}/brief.md`
+   - set `next_action`
+   - mark it `paused`, `delegated`, or leave `active` only if work continues
+3. Create a stable stream id from the goal, such as `billing-webhooks`.
+4. Create:
+   - `.forge/streams/{id}.yml` from `.forge/templates/streams/stream.yml`
+   - `.forge/streams/{id}/brief.md` from `.forge/templates/streams/brief.md`
+   - `.forge/streams/{id}/packages/`
+5. Add a compact entry to `.forge/streams/active.yml`.
+6. Declare ownership:
+   - `owned_surfaces` for files or areas the stream may edit
+   - `shared_surfaces` for contracts, APIs, schemas, or docs touched with care
+   - `read_only_surfaces` for context only
+   - `forbidden_surfaces` for explicit exclusions
+7. If ownership is uncertain, start read-only and ask for a narrower boundary.
+8. Run conflict detection before making edits.
+
+## Adopt Existing M10 Worktrees Flow
+
+Use this when a repo already has `orchestrating` / M10 worktrees running and the
+user asks to move to Chief/Streams. Do not teardown, merge, rebase, or remove
+worktrees as part of adoption. Adoption only creates stream metadata around
+existing M10 state.
+
+1. Read or create `.forge/streams/active.yml`.
+2. Discover live M10 worktrees from both sources:
+   - `git worktree list --porcelain` branches matching `refs/heads/forge/m-*`
+   - `.forge/state/milestone-*.yml` with
+     `lifecycle.worktree_mode: active` or `degraded`
+3. For each discovered worktree, read its milestone state when available:
+   - milestone id and name
+   - `current.status`, `current.phase`, `current.phase_name`
+   - `lifecycle.worktree_path`
+   - `lifecycle.worktree_branch`
+   - `lifecycle.worktree_anchor`
+   - `lifecycle.session_id`
+   - `lifecycle.claim_session_id`
+   - blockers or refused/degraded reason
+4. Create a stable stream id. Prefer a slug from milestone id + name, for
+   example `m16-chief-streams`. If only the branch is known, derive from the
+   branch suffix.
+5. For each adopted stream, create if missing:
+   - `.forge/streams/{id}.yml`
+   - `.forge/streams/{id}/brief.md`
+   - `.forge/streams/{id}/packages/`
+6. Populate the stream file:
+   - `stream.id`, `goal`, `status`, `tier`
+   - `runtime.branch` from `lifecycle.worktree_branch`
+   - `runtime.worktree` from `lifecycle.worktree_path`. **If no path was
+     recorded** (a manual `git worktree add`, or pre-convention state), resolve
+     it from the base **Worktree Convention** in `FORGE.md` —
+     `{orchestration.worktree_root or ../<repo>-worktrees}/{anchor}` — rather
+     than assuming the experimental `orchestrating` skill's internal default.
+     Confirm the resolved path with `git worktree list` before recording it.
+   - `runtime.worker_sessions` with the M10 session / claim ids
+   - `ownership.owned_surfaces`, `shared_surfaces`, and `read_only_surfaces`
+     as empty lists if unknown
+   - `blockers` from milestone blockers or degraded/refused notes
+   - `context.milestone` pointing at `.forge/state/milestone-{id}.yml`
+7. Populate the stream brief with:
+   - current milestone/phase/status
+   - worktree path and branch
+   - known blockers
+   - unknown ownership surfaces marked as needing declaration
+   - next action from milestone state or "declare ownership and sync"
+8. Add or update the compact entry in `.forge/streams/active.yml`.
+9. Run conflict detection. Missing ownership is a conflict until clarified, but
+   it does not block adoption.
+10. Ask before changing `.forge/project.yml`:
+    - If the user confirms Chief should be the front door, set
+      `orchestration.auto: false`.
+    - If not confirmed, leave legacy M10 auto-routing unchanged.
+
+Adoption is idempotent. If a stream already references the same worktree branch
+or path, update its summary and brief instead of creating a duplicate stream.
+
+## Pause And Resume Flow
+
+Pause:
+1. Update the stream brief with current state, decisions, blockers, and next
+   action.
+2. Set registry status to `paused`, unless work was handed to another session
+   and should be `delegated`.
+3. Clear `current_stream` only if no stream remains active in this session.
+
+Resume:
+1. Load registry, stream file, and brief.
+2. Surface status, blockers, owned surfaces, shared surfaces, and next action.
+3. Set the stream to `active`.
+4. Run conflict detection before continuing.
+
+## Delegate Flow
+
+1. Confirm the stream has a clear goal and ownership boundary.
+2. Copy `.forge/templates/streams/work-package.yml` to
+   `.forge/streams/{stream}/packages/{id}.yml`.
+3. Include goal, owned/read-only/forbidden surfaces, deliverables, verification
+   commands, stop conditions, and reporting target.
+4. Mark the stream `delegated` if the worker owns the next action.
+5. Tell the worker to report back to the Chief, not to other workers.
+6. If the worker finds conflicts, missing contracts, blocked verification, or
+   scope expansion, they stop and report back before editing outside package
+   scope.
+
+If the work-package template is not present yet, create the smallest package
+shape that preserves goal, surfaces, deliverables, stop conditions, and next
+reporting step. Phase 25 upgrades this to the full schema.
+
+Delegation prompt must name the package path and the reporting target:
+
+```text
+Work from `.forge/streams/{stream}/packages/{id}.yml`.
+Edit only `scope.owns`.
+Read `scope.may_read` for context.
+Do not touch `scope.must_not_touch`.
+Report conflicts, missing contracts, blocked verification, or scope expansion
+back to the Chief. Do not coordinate directly with other workers.
+```
+
+## Detect Conflicts
+
+Compare all `active`, `delegated`, and `ready` streams:
+
+- overlapping `owned_surfaces` means serialize, split, or block one stream
+- `owned_surfaces` overlapping another stream's `shared_surfaces` requires a
+  reservation, contract, or explicit merge order
+- overlapping `shared_surfaces` requires a named contract owner
+- overlapping `read_only_surfaces` is safe
+- missing ownership is a conflict until clarified
+
+Record conflicts in both the registry and the affected stream files. Do not let
+workers resolve cross-stream conflicts directly.
+
+## Merge Safe Flow
+
+Use "merge safe" to identify streams that can land:
+
+1. Candidate stream status must be `ready`.
+2. No blockers may be open.
+3. Owned surfaces must not overlap another active or ready stream.
+4. Shared surfaces must have a contract owner and documented validation.
+5. Verification commands or manual validation must be listed.
+6. Merge order must be explicit when more than one stream is ready.
+
+If any condition fails, mark the stream blocked or keep it ready with a named
+reason it cannot merge yet.
+
+## Close Flow
+
+1. Confirm final status: merged, intentionally abandoned, superseded, or split.
+2. Record final outcome in the stream brief.
+3. Update registry status to `closed`.
+4. Clear `current_stream` if this was the active stream.
+5. Keep closed stream history available until a later archive/compaction pass.
+
+## Output Shape
+
+Keep Chief responses short and operational:
+
+```text
+Streams:
+- billing-webhooks — active — owns api/billing, shared db/schema — next: verify webhook retries
+- settings-ui — paused — owns app/settings — next: resume form validation
+
+Conflicts:
+- billing-webhooks and reporting-export both touch db/schema. Contract owner needed before either merges.
+
+Next:
+- Continue billing-webhooks, or start a new stream with read-only ownership until boundaries are declared.
+```

package/template/.claude/skills/discussing/SKILL.md

@@ -45,10 +45,12 @@ Never accumulate decisions in working memory. Never batch writes to convergence.
 `context.md` is **shared mutable** state per FORGE.md State Ownership — writes follow two structural rules:
 - **Scope to your milestone's block.** Different milestone blocks → git merges cleanly across worktrees.
 - **Append-only within a block.** When superseding an older decision, *strike through* (`~~old decision~~`) and append the new line below — never rewrite in place. Same-line concurrent edits become impossible by construction; reading the history of a decision becomes possible by inspection.
+- **Keep active context active.** Write current/open decisions to `.forge/context.md`. Do not rehydrate old milestone blocks from `.forge/context-archive.md` unless the user is amending that historical decision.
 
 **On first decision of the session:**
 - Check if `.forge/context.md` exists. If not → create it from `.forge/templates/context.md`
 - Add a milestone heading inside `## Locked Decisions`: `### M{id} — {name} (drafting)` (use "M?" if no milestone yet)
+- If the needed historical decision is archived, cite the archive in the new active decision instead of copying the whole block back.
 - **Cross-tree liveness check (informational).** If editing an existing block for milestone `{id}`, run `git worktree list --porcelain | awk '/^branch / && $2 ~ /refs\/heads\/forge\/m-'"$id"'(-|$)/ {print}'`. Any hit means m{id} is **live in another worktree** — surface one line: *"m{id} is live in worktree at `{path}`. Edits land cleanly on main but won't be visible to that worktree until it rebases or pulls."* Proceed with the write — main is often the canonical author of `context.md`, this is a heads-up, not a block.
 
 **On each confirmed decision:**

package/template/.claude/skills/forge/SKILL.md

@@ -163,7 +163,12 @@ No `project.yml` + Standard/Full → **Step 2A**. State exists → **Step 2B**.
 
 ## Step 1.5: Lifecycle Operations
 
-Before tier detection, check if user request matches lifecycle patterns:
+Before tier detection, check if user request matches stream or lifecycle patterns:
+- "show streams" / "active streams" / "what streams are active" / "stream status" → **Show Streams**
+- "start stream {name}" / "new stream {name}" / "create stream {name}" / "pivot to {work}" → **Start Stream**
+- "pause stream {id}" / "resume stream {id}" / "delegate stream {id}" / "sync streams" → **Manage Streams**
+- "detect conflicts" / "check stream conflicts" / "merge safe" / "close stream {id}" → **Manage Streams**
+- "Chief of Staff" / "Project Chief" / "use streams" / "parallel workstreams" → **Chief**
 - "defer milestone {id}" / "defer {id}" / "pause milestone {id}" → **Defer**
 - "resume milestone {id}" / "undefer {id}" / "reactivate milestone {id}" → **Resume**
 - "delete milestone {id}" / "archive milestone {id}" / "remove milestone {id}" → **Delete** (see below)
@@ -171,6 +176,22 @@ Before tier detection, check if user request matches lifecycle patterns:
 
 No match → fall through to Step 2B (tier detection).
 
+### Chief / Stream Operations
+
+1. Invoke `Skill(chief-of-staff)` directly.
+2. Do not enter tier detection. The Chief is project-level traffic control, not
+   a replacement for Forge's Quick, Standard, or Full tiers.
+3. Use Chief only for explicit stream intents, concurrent application work,
+   mid-flow pivots, delegated work, conflict detection, merge ordering, or
+   closing streams.
+4. Ordinary single-stream feature work still follows normal tier detection.
+   Once inside a stream, the stream uses Quick/Standard/Full for execution.
+
+Examples:
+- "show streams" → `Skill(chief-of-staff)` summarizes `.forge/streams/active.yml`
+- "start stream settings cleanup" → `Skill(chief-of-staff)` snapshots current stream, creates a new stream, and checks conflicts
+- "merge safe?" → `Skill(chief-of-staff)` lists ready streams that can land without blocking conflicts
+
 ### Show Deferred
 
 1. Invoke `Skill(deferred)` directly.
@@ -262,13 +283,17 @@ Tier + state → invoke via `Skill` tool. All phases use `Skill()`.
 
 **CRITICAL: NEVER `EnterPlanMode`.** "Planning" = `Skill(planning)`. Native plan mode writes wrong format, bypasses gates + state.
 
-**Experimental — M10 orchestration (auto-routes when installed).** Installing M10 *is* the consent: `forge` then auto-routes Standard/Full work through `orchestrating` **before** `executing` — no separate invocation to remember. Route through `Skill(orchestrating)` first when **all** hold:
+**Experimental — M10 orchestration backend.** Chief/Streams is the preferred
+user-facing orchestration model. M10 remains an optional backend for streams
+that need worktree isolation, merge-queue discipline, or experimental file
+claims. Route through `Skill(orchestrating)` first when **all** hold:
+- **Selected:** Project Chief chooses M10 for a stream, user explicitly asks for multi-agent/worktree mode, or legacy `orchestration.auto` is enabled.
 - **Installed:** `.claude/skills/orchestrating/` present + `forge-orchestrator` in `.mcp.json` + `.claude/hooks/forge-claim-check.sh` present.
-- **Not opted out:** `orchestration.auto` in `project.yml` ≠ `false` (absent = on; install = consent per ADR-001).
+- **Not opted out:** `orchestration.auto` in `project.yml` ≠ `false` for legacy auto-routing; explicit Project Chief selection can still use M10 when installed.
 - **Tier is Standard or Full.** Quick never auto-orchestrates (a worktree per typo is the wrong trade).
 - **Not already in a session:** active milestone has no `lifecycle.worktree_mode: active|degraded` (don't re-bootstrap inside a live session).
 
-`orchestrating` bootstrap stays the safety net — incompatible repo → it refuses, writes `worktree_mode: refused`, and `forge` continues single-agent. Absent install → standard routing. Manual `Skill(orchestrating)` still works for explicit control; set `orchestration.auto: false` in `project.yml` to opt back out.
+`orchestrating` bootstrap stays the safety net — incompatible repo → it refuses, writes `worktree_mode: refused`, and `forge` continues single-agent. Absent install → standard routing. Manual `Skill(orchestrating)` still works for explicit backend control; set `orchestration.auto: false` in `project.yml` to opt out of legacy auto-routing.
 
 ### Auto-Routing (Always Deterministic)
 
@@ -307,6 +332,7 @@ Where `{source}` = `skills.{name}` | `models.default` | `parent session`. Suppre
 | discussing | sonnet | Conversation |
 | testing | sonnet | Code gen (author) + audit judgment (analyst) — matches executing/reviewing. M9: author-mode refuses e2e without `e2e:true` + `validated:true`. |
 | deferred | haiku | Read + format only |
+| chief-of-staff | sonnet | Cross-stream coordination and conflict judgment |
 
 | `current.status` | Route To |
 |-------------------|----------|
@@ -322,6 +348,7 @@ Where `{source}` = `skills.{name}` | `models.default` | `parent session`. Suppre
 | `deferred` | Milestone frozen. *"Resume milestone {id}" to reactivate.* |
 | `quick-tasking` | `Skill(quick-tasking)` |
 | (keyword: `deferred` / "show deferred") | `Skill(deferred)` — read-only aggregator |
+| (keyword: `show streams` / `start stream` / `merge safe` / `Chief of Staff`) | `Skill(chief-of-staff)` — project stream coordination |
 
 ### Status Advancement Check
 

package/template/.claude/skills/planning/SKILL.md

@@ -32,6 +32,11 @@ If you find yourself writing a plan that only touches `src/models/`, `src/db/`,
 Read `.forge/context.md` **Needs Resolution**. If unchecked `- [ ]` items:
 *"{N} items need input: [list]. For each: lock, defer, fix, or drop?"*
 
+Load `.forge/context.md` as the active decision set. Consult
+`.forge/context-archive.md` only when the current milestone, stream, or
+requirement cites an older milestone decision (for example M9 e2e policy or M14
+backlog lifecycle). Do not load archived decision blocks wholesale.
+
 | Choice | Action |
 |--------|--------|
 | Lock | Record in Locked Decisions |
@@ -61,6 +66,10 @@ If missing, create `.forge/context.md` from template:
 
 Must complete BEFORE plans. Plans reference context.md.
 
+If a plan depends on an archived decision, cite the archive section in the plan
+or active context summary; do not copy the historical block back into
+`.forge/context.md`.
+
 ## Step 4: Structure Requirements
 
 Resolve current milestone ID from `.forge/state/index.yml` (active milestone) or invocation context. Target file: `.forge/requirements/m{N}.yml`.

package/template/.claude/skills/upgrading/SKILL.md

@@ -43,7 +43,7 @@ Read the source version (`{source}/packages/create-forge/package.json` `version`
 
 **Never touch** user-generated files: `.forge/project.yml`, `.forge/state/`, `.forge/constitution.md`, `.forge/context.md`, `.forge/requirements/`, `.forge/roadmap.yml`, `.forge/design-system.md`, `.forge/refactor-backlog.yml`.
 
-**Preserve experimental skills.** Opt-in skills installed separately (e.g. `.claude/skills/orchestrating/` from `experimental/m10/`) are not in the base template. Never flag them as "removed from template" or delete them — leave them untouched.
+**Experimental skills — re-sync, don't blanket-skip.** Opt-in skills installed separately (e.g. `.claude/skills/orchestrating/` from `experimental/m10/`) are not in the base template, so they never appear in the Step 3 base sync. Earlier guidance was to leave them *untouched* — but that silently froze them at install-time content, so a base-template migration that changes behavior living only in an experimental skill became a no-op (the version stamp advanced and the migration doc shipped, yet the behavior never landed — e.g. the 0.28.0 repo-scoped worktree root). Step 3b now gives experimental skills their own **detect-and-offer-re-sync** pass against their `experimental/*/source/` origin. Never auto-overwrite and never flag them "removed from template" — but never leave staleness invisible either.
 
 ## Step 3: Sync Framework-Owned Files
 
@@ -53,7 +53,31 @@ For each framework-owned file in the source template:
 2. Different → overwrite local, report **updated**
 3. Same → report **unchanged**
 4. Source has new file → copy, report **added**
-5. Local has file not in source → report **removed from template** (don't delete -- let user decide)
+5. Local has file not in source → it may be an **experimental** skill — defer the verdict to Step 3b, which distinguishes "experimental, has a known source" from "genuinely removed from template." Only skills with no experimental source are reported **removed from template** (don't delete -- let user decide).
+
+## Step 3b: Re-sync Experimental Skills (detect + offer, never blanket-skip)
+
+Experimental skills are installed from `{source}/packages/create-forge/experimental/<pkg>/source/skills/<name>/`, not the base template — so Step 3 never sees them. Without this pass they freeze at install-time content forever (issue #5). This pass makes staleness **visible and one-click-fixable** while staying non-destructive.
+
+For each skill dir present in the project's `.claude/skills/` but **absent from the base template**:
+
+1. Search the source for a matching experimental origin: `{source}/packages/create-forge/experimental/*/source/skills/<name>/`.
+2. **No match** → genuinely local / removed-from-template. Report **removed from template** (don't delete) as before. Done.
+3. **Match found** → it is an experimental skill with a known upstream. Diff each markdown file in the installed dir against the source dir (`SKILL.md` and any siblings, e.g. `bootstrap-checks.md`):
+   - **All identical** → report `{name}: experimental, unchanged`.
+   - **Differs** → report `{name}: experimental, STALE (pinned at install; source has changes)` and **offer** a re-sync with the same preview/confirm UX as base skills:
+
+     ```
+     {name} is an experimental skill (from experimental/{pkg}/) pinned at install time.
+     The release ships newer content. Files that differ: {list}.
+     Re-sync from experimental/{pkg}/source? (yes / show diff / no)
+     ```
+
+     - **yes** → overwrite the installed skill's markdown files from source; report **updated (experimental)**.
+     - **show diff** → display the diff(s), then re-ask.
+     - **no** → leave untouched; note in the report that it stays pinned.
+
+**Default is non-destructive** — never overwrite an experimental skill without an explicit `yes`. **Scope:** this pass re-syncs the skill's **markdown** (the behavior-bearing prose). It does **not** touch the experimental package's hooks, MCP server, or `settings.json`/`.mcp.json` wiring — those are owned by the package's own installer. When a re-sync lands, add one line: *"Hooks / MCP server for {pkg} are not re-synced here — re-run `experimental/{pkg}/install.sh` if the release changed them."*
 
 ## Step 4: Sync Template-Only Files
 
@@ -97,6 +121,10 @@ Added: {N} files
   - .claude/skills/new-skill/SKILL.md
   - ...
 
+Experimental skills: {N}
+  - orchestrating (from experimental/m10) — updated  [or: unchanged / STALE, declined]
+  - ...
+
 Removed from template: {N} files
   - .claude/agents/old-agent.md (still in your project)
   - ...