forge-orkes 0.2.0 → 0.3.1

package/bin/create-forge.js

@@ -6,6 +6,23 @@ const readline = require('readline');
 
 const templateDir = path.join(__dirname, '..', 'template');
 const targetDir = process.cwd();
+const pkgVersion = require('../package.json').version;
+
+// --- File classification for upgrades ---
+
+// Framework-owned: Forge controls these entirely
+const FRAMEWORK_OWNED_DIRS = ['.claude/agents', '.claude/skills'];
+
+// Template-only: reference templates Forge controls
+const TEMPLATE_ONLY_DIRS = ['.forge/templates'];
+
+// Merge-owned: never auto-overwrite, stage for review
+const MERGE_OWNED_FILES = ['CLAUDE.md'];
+
+// Settings file gets smart-merge (overwrite forge.* keys, preserve user hooks)
+const SETTINGS_FILE = '.claude/settings.json';
+
+// --- Helpers ---
 
 function copyDirRecursive(src, dest) {
   let count = 0;
@@ -38,7 +55,132 @@ function prompt(question) {
   });
 }
 
-async function main() {
+function stampVersion(settingsPath) {
+  const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+  if (settings.forge) {
+    settings.forge.version = pkgVersion;
+  }
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+}
+
+/**
+ * Recursively collect all relative file paths under a directory.
+ */
+function collectFiles(dir, base) {
+  const results = [];
+  if (!fs.existsSync(dir)) return results;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const rel = path.join(base, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...collectFiles(path.join(dir, entry.name), rel));
+    } else {
+      results.push(rel);
+    }
+  }
+  return results;
+}
+
+/**
+ * Compare and overwrite framework-owned or template-only files.
+ * Returns { updated, added, unchanged, removed } arrays of relative paths.
+ */
+function upgradeDir(relDir) {
+  const srcDir = path.join(templateDir, relDir);
+  const destDir = path.join(targetDir, relDir);
+
+  const result = { updated: [], added: [], unchanged: [], removed: [] };
+
+  if (!fs.existsSync(srcDir)) return result;
+
+  const srcFiles = collectFiles(srcDir, '');
+  const destFiles = new Set(collectFiles(destDir, ''));
+
+  for (const rel of srcFiles) {
+    const srcPath = path.join(srcDir, rel);
+    const destPath = path.join(destDir, rel);
+    const displayPath = path.join(relDir, rel);
+
+    if (!fs.existsSync(destPath)) {
+      fs.mkdirSync(path.dirname(destPath), { recursive: true });
+      fs.copyFileSync(srcPath, destPath);
+      result.added.push(displayPath);
+    } else {
+      const srcContent = fs.readFileSync(srcPath);
+      const destContent = fs.readFileSync(destPath);
+      if (Buffer.compare(srcContent, destContent) !== 0) {
+        fs.copyFileSync(srcPath, destPath);
+        result.updated.push(displayPath);
+      } else {
+        result.unchanged.push(displayPath);
+      }
+    }
+  }
+
+  // Detect files in dest that are no longer in template
+  for (const rel of destFiles) {
+    const srcPath = path.join(srcDir, rel);
+    if (!fs.existsSync(srcPath)) {
+      result.removed.push(path.join(relDir, rel));
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Handle merge-owned files: stage new version for manual review if different.
+ */
+function handleMergeFile(relFile) {
+  const srcPath = path.join(templateDir, relFile);
+  const destPath = path.join(targetDir, relFile);
+
+  if (!fs.existsSync(srcPath)) return null;
+  if (!fs.existsSync(destPath)) return null;
+
+  const srcContent = fs.readFileSync(srcPath, 'utf-8');
+  const destContent = fs.readFileSync(destPath, 'utf-8');
+
+  if (srcContent === destContent) return 'unchanged';
+
+  // Stage the new version for manual review
+  const upgradeDir = path.join(targetDir, '.forge', 'upgrade');
+  fs.mkdirSync(upgradeDir, { recursive: true });
+  const basename = path.basename(relFile);
+  const newPath = path.join(upgradeDir, `${basename}.new`);
+  fs.writeFileSync(newPath, srcContent);
+  return 'staged';
+}
+
+/**
+ * Smart-merge settings.json: overwrite forge.* keys from template, preserve user hooks.
+ */
+function upgradeSettings() {
+  const srcPath = path.join(templateDir, SETTINGS_FILE);
+  const destPath = path.join(targetDir, SETTINGS_FILE);
+
+  if (!fs.existsSync(destPath)) return 'missing';
+  if (!fs.existsSync(srcPath)) return 'missing';
+
+  const srcSettings = JSON.parse(fs.readFileSync(srcPath, 'utf-8'));
+  const destSettings = JSON.parse(fs.readFileSync(destPath, 'utf-8'));
+
+  const before = JSON.stringify(destSettings);
+
+  // Overwrite forge.* keys from template
+  destSettings.forge = { ...destSettings.forge, ...srcSettings.forge };
+  // Always stamp current package version
+  destSettings.forge.version = pkgVersion;
+
+  const after = JSON.stringify(destSettings);
+  if (before === after) return 'unchanged';
+
+  fs.writeFileSync(destPath, JSON.stringify(destSettings, null, 2) + '\n');
+  return 'updated';
+}
+
+// --- Commands ---
+
+async function install() {
   console.log('\n  Forge - Meta-prompting framework for Claude Code\n');
 
   // Handle CLAUDE.md
@@ -94,10 +236,139 @@ async function main() {
   const forgeCount = copyDirRecursive(srcForge, destForge);
   console.log(`  Installed .forge/templates/ (${forgeCount} files)`);
 
-  console.log('\n  Forge is ready. Start with: /forge\n');
+  // Stamp version from package.json into settings.json
+  const settingsPath = path.join(targetDir, SETTINGS_FILE);
+  if (fs.existsSync(settingsPath)) {
+    stampVersion(settingsPath);
+  }
+
+  console.log(`\n  Forge v${pkgVersion} is ready. Start with: /forge\n`);
 }
 
-main().catch((err) => {
-  console.error('Error:', err.message);
-  process.exit(1);
-});
+async function upgrade() {
+  console.log('\n  Forge Upgrade\n');
+
+  // Verify Forge is installed
+  const settingsPath = path.join(targetDir, SETTINGS_FILE);
+  if (!fs.existsSync(settingsPath)) {
+    console.error(
+      '  Forge is not installed in this directory.\n  Run `npx forge-orkes` first to install.\n'
+    );
+    process.exit(1);
+  }
+
+  // Read installed version
+  let installedVersion = 'unknown';
+  try {
+    const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+    installedVersion = settings.forge?.version || 'unknown';
+  } catch {
+    // proceed with unknown version
+  }
+
+  console.log(`  Installed: v${installedVersion}`);
+  console.log(`  Available: v${pkgVersion}\n`);
+
+  const results = {
+    updated: [],
+    added: [],
+    unchanged: [],
+    removed: [],
+    needsReview: [],
+  };
+
+  // 1. Process framework-owned directories
+  for (const dir of FRAMEWORK_OWNED_DIRS) {
+    const dirResult = upgradeDir(dir);
+    results.updated.push(...dirResult.updated);
+    results.added.push(...dirResult.added);
+    results.unchanged.push(...dirResult.unchanged);
+    results.removed.push(...dirResult.removed);
+  }
+
+  // 2. Process template-only directories
+  for (const dir of TEMPLATE_ONLY_DIRS) {
+    const dirResult = upgradeDir(dir);
+    results.updated.push(...dirResult.updated);
+    results.added.push(...dirResult.added);
+    results.unchanged.push(...dirResult.unchanged);
+    results.removed.push(...dirResult.removed);
+  }
+
+  // 3. Process merge-owned files
+  for (const file of MERGE_OWNED_FILES) {
+    const status = handleMergeFile(file);
+    if (status === 'staged') {
+      results.needsReview.push(file);
+    } else if (status === 'unchanged') {
+      results.unchanged.push(file);
+    }
+  }
+
+  // 4. Smart-merge settings.json
+  const settingsStatus = upgradeSettings();
+  if (settingsStatus === 'updated') {
+    results.updated.push(SETTINGS_FILE);
+  } else if (settingsStatus === 'unchanged') {
+    results.unchanged.push(SETTINGS_FILE);
+  }
+
+  // Report results
+  const totalChanges =
+    results.updated.length + results.added.length + results.needsReview.length;
+
+  if (totalChanges === 0 && results.removed.length === 0) {
+    console.log('  Already up to date.\n');
+    return;
+  }
+
+  if (results.updated.length > 0) {
+    console.log(`  Updated (${results.updated.length}):`);
+    for (const f of results.updated) {
+      console.log(`    ${f}`);
+    }
+    console.log();
+  }
+
+  if (results.added.length > 0) {
+    console.log(`  Added (${results.added.length}):`);
+    for (const f of results.added) {
+      console.log(`    ${f}`);
+    }
+    console.log();
+  }
+
+  if (results.needsReview.length > 0) {
+    console.log(`  Needs manual review (${results.needsReview.length}):`);
+    for (const f of results.needsReview) {
+      console.log(`    ${f} → .forge/upgrade/${path.basename(f)}.new`);
+    }
+    console.log();
+  }
+
+  if (results.removed.length > 0) {
+    console.log(`  Removed from template (${results.removed.length}):`);
+    for (const f of results.removed) {
+      console.log(`    ${f} (still in your project — delete manually if unused)`);
+    }
+    console.log();
+  }
+
+  console.log(`  Upgraded to v${pkgVersion}\n`);
+}
+
+// --- Entry point ---
+
+const subcommand = process.argv[2];
+
+if (subcommand === 'upgrade') {
+  upgrade().catch((err) => {
+    console.error('Error:', err.message);
+    process.exit(1);
+  });
+} else {
+  install().catch((err) => {
+    console.error('Error:', err.message);
+    process.exit(1);
+  });
+}

package/package.json

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

package/template/.claude/settings.json

@@ -1,6 +1,6 @@
 {
   "forge": {
-    "version": "0.1.0",
+    "version": "0.3.1",
     "default_tier": "standard",
     "beads_integration": false,
     "context_gates": {
@@ -10,7 +10,14 @@
       "constitution_md_max_kb": 10
     },
     "commit_format": "{type}({scope}): {description}",
-    "commit_types": ["feat", "fix", "test", "refactor", "chore", "docs"]
+    "commit_types": [
+      "feat",
+      "fix",
+      "test",
+      "refactor",
+      "chore",
+      "docs"
+    ]
   },
   "hooks": {
     "PostToolUse": [
@@ -23,9 +30,27 @@
             "async": true
           }
         ]
+      },
+      {
+        "matcher": "Skill",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "mkdir -p .forge && echo \"$TOOL_INPUT\" > .forge/.active-skill"
+          }
+        ]
       }
     ],
     "PreToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [ ! -f .forge/.active-skill ]; then echo \"[Forge] No active skill. Invoke /forge or /quick-tasking before editing code. To bypass: touch .forge/.active-skill\" >&2; exit 2; fi"
+          }
+        ]
+      },
       {
         "matcher": "Bash(git commit)",
         "hooks": [

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

@@ -44,44 +44,79 @@ Read: .forge/constitution.md → active gates (if exists)
 
 Check if research findings were written to files (`.forge/phases/` or similar). If so, read them. If research was inline-only (conversation context), the findings may need to be re-summarized from the user — ask briefly: *"We're picking up after the research phase. Can you summarize the key findings, or should I re-scan the relevant areas?"*
 
-### Step 1: Present the Landscape
+### Step 1: Present Decisions with AskUserQuestion
 
 Summarize what research found, structured around decisions the user needs to make — not a data dump.
 
-*"Based on what I found, here are the key decisions before we plan:"*
+**Use the `AskUserQuestion` tool for every decision point.** This gives users a clean, scannable interface instead of walls of text. You can batch up to 4 questions per `AskUserQuestion` call.
 
-For each decision point:
-- **What needs deciding** — the question, stated plainly
-- **Options** — 2-3 realistic approaches (not exhaustive lists)
-- **Trade-offs** — what you gain and what you lose with each
-- **Recommendation** — if you have one, say so and say why. If you don't, say that too.
+For each decision:
+1. Write a **brief prose intro** (2-3 sentences max) setting context for the decision — what's the problem, why does it matter.
+2. Then immediately call `AskUserQuestion` with:
+   - `question`: The decision stated plainly, ending with `?`
+   - `header`: Short label (e.g., "Strategy", "Approach", "Scope")
+   - `options`: 2-4 realistic approaches. Each option gets:
+     - `label`: Concise name (1-5 words). Put your recommendation first with "(Recommended)" suffix.
+     - `description`: Trade-offs — what you gain and what you lose. Be honest about costs.
+   - `multiSelect`: false for mutually exclusive choices, true when combinations are valid.
 
-Keep it conversational. Don't present a 20-item matrix. Surface the 3-5 decisions that actually matter for this work.
+**Batch related decisions.** If you have 3-5 decisions, group them into 1-2 `AskUserQuestion` calls (max 4 questions each) rather than asking one at a time. This lets the user see the full landscape and make coherent choices.
+
+**When NOT to use AskUserQuestion:** For open-ended exploration questions where the answer isn't one of a few discrete options (e.g., "Walk me through the ideal user flow"), use regular prose. The tool is for decisions with concrete choices, not brainstorming.
+
+Example structure for a discussion with 3 decisions:
+
+```
+Brief context paragraph explaining the landscape from research.
+
+→ AskUserQuestion with questions:
+  1. "Which recovery strategy should we use?" (header: "Recovery")
+     - "Sweep timer (Recommended)" / "Sweep timer + queue refactor" / ...
+  2. "Where should observability live?" (header: "Observability")
+     - "Server-side logs only" / "PostHog events" / "Both" / ...
+  3. "How should we handle the 704 contradictory records?" (header: "Data cleanup")
+     - "Migration + constraints" / "Let sweep handle it" / "Migration only" / ...
+```
+
+Surface the 3-5 decisions that actually matter. Don't present a 20-item matrix.
 
 ### Step 2: Facilitate, Don't Dictate
 
-Your role is to help the user think, not to push them toward your preference.
+After the user responds to decisions, your role is to help them think deeper — not to push your preference.
+
+**Use `AskUserQuestion` for follow-up decisions** that emerge from their answers. Use prose for open-ended exploration.
 
 Good facilitation patterns:
-- *"The main tension here is between X and Y. Which matters more for your project?"*
-- *"Option A is simpler now but harder to change later. Option B is more work upfront but more flexible. What's your timeline pressure like?"*
-- *"I'd lean toward X because [reason], but Y makes sense if [condition]. What's your read?"*
-- *"You mentioned [earlier decision] — that makes Option B a more natural fit. Does that match your thinking?"*
+- *"The main tension here is between X and Y."* → then `AskUserQuestion` with the concrete options
+- Referencing earlier decisions: *"You chose Option A for recovery — that makes X a more natural fit for observability."* → then `AskUserQuestion` with refined options
+- When trade-offs need explicit weighing → `AskUserQuestion` with `description` fields that name the costs
 
 Bad facilitation patterns:
-- Presenting options without trade-offs (just a list)
-- Asking "what do you think?" without giving the user something to react to
+- Presenting options as prose paragraphs when they could be `AskUserQuestion` choices
+- Asking "what do you think?" without giving the user something concrete to react to
 - Overwhelming with edge cases before the main path is clear
 - Treating every decision as equally important
 
 ### Step 3: Probe for Hidden Constraints
 
-Research often misses things the user knows but hasn't mentioned. Ask about:
-- **Timeline pressure** — does this need to ship by a date?
-- **Audience/users** — who actually uses this? (affects complexity trade-offs)
-- **Future direction** — is this a throwaway or the foundation for more?
-- **Past experience** — have they tried something similar before? What went wrong?
-- **Strong preferences** — anything they definitely want or definitely don't want?
+Research often misses things the user knows but hasn't mentioned. Use `AskUserQuestion` for structured probes where the answer shapes the plan:
+
+```
+AskUserQuestion:
+  question: "What's the timeline pressure for this work?"
+  header: "Timeline"
+  options:
+    - label: "Ship this week"
+      description: "Minimal scope, skip nice-to-haves"
+    - label: "Ship this month"
+      description: "Room for polish and edge cases"
+    - label: "No hard deadline"
+      description: "Do it right, scope is flexible"
+```
+
+For open-ended probes where you need the user to explain (not choose), use prose:
+- *"Have you tried something similar before? What went wrong?"*
+- *"Anything you definitely want or definitely don't want?"*
 
 One or two questions at a time. Don't interrogate.
 
@@ -136,6 +171,21 @@ Don't mechanically walk through all 5 layers for every requirement — that woul
 
 Ask 2-3 questions at a time, let the user respond, then go deeper where their answers reveal uncertainty. The conversation should feel like a collaborative design session, not an interrogation.
 
+**Use `AskUserQuestion` for behavior decisions within distillation.** When a question has discrete answers (retry vs. fail vs. alert, real-time vs. polling, roles A/B/C), use the tool. When you need the user to describe or explain something open-ended, use prose.
+
+Example — Layer 3 question as `AskUserQuestion`:
+```
+question: "When the external enrichment API is down, what should the system do?"
+header: "Failure mode"
+options:
+  - label: "Retry with backoff (Recommended)"
+    description: "Queue retries at 1m/5m/30m intervals. Adds complexity but self-heals."
+  - label: "Fail and alert"
+    description: "Mark as failed, send alert. Simple but requires manual re-trigger."
+  - label: "Skip and continue"
+    description: "Process remaining items, revisit failures in next sweep."
+```
+
 **What you're listening for:**
 
 - **Contradictions** — "It should be simple" but also "it needs to handle 12 different states." Surface these gently.
@@ -145,14 +195,25 @@ Ask 2-3 questions at a time, let the user respond, then go deeper where their an
 
 ### Step 5: Converge on Decisions
 
-When the conversation has covered the key points, summarize what's been decided:
+When the conversation has covered the key points, summarize what's been decided as a brief prose list, then use `AskUserQuestion` for final confirmation:
 
-*"Here's where I think we've landed:*
+*"Here's where I think we've landed:"*
 - *[Decision 1]: [what was decided and why]*
 - *[Decision 2]: [what was decided and why]*
 - *[Open question]: [what's still unresolved and how to handle it]*
 
-*Does this match your understanding? If so, I'll carry these into planning."*
+Then confirm with `AskUserQuestion`:
+```
+question: "Does this match your understanding? Ready to move to planning?"
+header: "Confirm"
+options:
+  - label: "Looks good, proceed"
+    description: "Lock these decisions and move to planning phase."
+  - label: "I want to adjust something"
+    description: "Revisit one or more decisions before locking."
+  - label: "More to discuss"
+    description: "There are topics we haven't covered yet."
+```
 
 These decisions flow into `context.md` as **Locked Decisions** when the `planning` skill runs next.
 
@@ -182,12 +243,12 @@ Don't just recite the plan back. Translate it into what it means:
 
 ### Step 3: Surface What's Worth Discussing
 
-Don't wait for the user to spot issues. Proactively surface:
+Don't wait for the user to spot issues. Proactively surface concerns, then **use `AskUserQuestion` for any that have discrete choices:**
 
-- **Assumptions you're not confident about** — "Plan 01 assumes the API returns paginated results. I didn't verify this."
-- **Decisions that could go either way** — "I split this into 3 plans for parallelism, but you could also do it as 2 larger plans if you prefer fewer context switches."
-- **Risks the plan doesn't address** — "There's no fallback if the external API is slow. Worth adding, or accept the risk?"
-- **Scope questions** — "Plan 03 includes admin-only features. Ship those in v1, or defer?"
+- **Decisions that could go either way** → `AskUserQuestion` with the options and trade-offs
+- **Scope questions** → `AskUserQuestion` (e.g., "Ship admin features in v1?" with "Yes, include" / "Defer to v2" options)
+- **Risks the plan doesn't address** → `AskUserQuestion` (e.g., "Worth adding a fallback?" with "Add fallback" / "Accept risk" options)
+- **Assumptions you're not confident about** → Prose, since these need the user to confirm or correct rather than choose
 
 ### Step 4: Drill into Functionality
 
@@ -201,23 +262,43 @@ This is where post-planning discussion earns its keep — the plan makes the fea
 
 ### Step 5: Discuss and Revise Direction
 
-The user may want to:
-- **Change approach** — "Let's use WebSockets instead of polling." → Note this. Planning skill will rebuild the affected plans.
-- **Adjust scope** — "Defer the admin features." → Note this for deferred items.
-- **Reorder priorities** — "Do the dashboard before the settings page." → Note the new wave order.
-- **Ask questions** — "What happens if we skip the caching layer?" → Discuss implications honestly.
-- **Approve as-is** — "Looks good, proceed." → Move to executing.
+The user may want to change approach, adjust scope, reorder priorities, ask questions, or approve as-is. Use `AskUserQuestion` to give them a clear way to signal their intent:
+
+```
+question: "How would you like to proceed with this plan?"
+header: "Direction"
+options:
+  - label: "Approve as-is"
+    description: "Lock decisions and move to execution."
+  - label: "Adjust scope"
+    description: "Defer or add features before building."
+  - label: "Change approach"
+    description: "Revisit a technical decision in the plan."
+  - label: "More questions"
+    description: "I want to discuss specific parts further."
+```
+
+Based on their response, either drill deeper with follow-up `AskUserQuestion` calls or move to summarizing.
 
 ### Step 6: Summarize Changes
 
-If the discussion produced changes to the plan direction:
+If the discussion produced changes to the plan direction, summarize as prose:
 
 *"Based on our discussion:*
 - *[Change 1]: [what changed and why]*
 - *[Change 2]: [what changed and why]*
 - *[Unchanged]: [what stays the same]*
 
-*Next step: I'll update the plans to reflect this. Want me to proceed with re-planning, or is there more to discuss?"*
+Then confirm next steps with `AskUserQuestion`:
+```
+question: "Ready to update the plans, or more to discuss?"
+header: "Next step"
+options:
+  - label: "Update plans"
+    description: "Re-plan affected areas with the revised decisions."
+  - label: "More to discuss"
+    description: "There are topics we haven't covered yet."
+```
 
 If re-planning is needed, route back to the `planning` skill with the discussion summary as input. The planning skill will update plans, requirements, and context.md accordingly.
 

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

@@ -481,6 +481,12 @@ Match ANY:
 → Add `designing` if UI work involved
 → Add `securing` if auth/data/API touched
 
+### Direct Utility Skills
+Match ANY:
+- User says "upgrade", "update forge", "sync forge"
+
+→ Route to `upgrading` skill (bypasses tier detection)
+
 ### User Override
 If user explicitly says "Use Quick/Standard/Full tier" — honor it. No arguments.
 

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

@@ -0,0 +1,90 @@
+---
+name: upgrading
+description: "Sync Forge framework files from a local dev repo or NPM. Use when developing Forge itself or applying updates to an installed project."
+---
+
+# Upgrading: Local Dev Sync
+
+Sync framework files from a local Forge source repo into the current project. Use this during Forge development to test changes without publishing to NPM.
+
+For published upgrades, use `npx forge-orkes upgrade` instead.
+
+## Step 1: Resolve Source Path
+
+Check if `.forge/dev-source` exists in the project root.
+
+- **If it exists:** read the path from the file (first line, trimmed). Verify the path exists and contains `packages/create-forge/template/`.
+- **If it doesn't exist:** ask the user: *"Where is your local Forge repo? (e.g., ~/Dev/forge)"*
+  - Validate the path has `packages/create-forge/template/`
+  - Save the path to `.forge/dev-source` for next time
+
+The template directory is `{source}/packages/create-forge/template/`.
+
+## Step 2: File Classification
+
+Files are classified into three categories:
+
+| Category | Paths | Behavior |
+|----------|-------|----------|
+| **Framework-owned** | `.claude/agents/*.md`, `.claude/skills/*/SKILL.md` | Overwrite — these are Forge's |
+| **Merge-owned** | `CLAUDE.md`, `.claude/settings.json` | Never auto-overwrite |
+| **Template-only** | `.forge/templates/**` | Overwrite — reference templates |
+
+**Never touch** user-generated files: `.forge/project.yml`, `.forge/state/`, `.forge/constitution.md`, `.forge/context.md`, `.forge/requirements.yml`, `.forge/roadmap.yml`, `.forge/design-system.md`, `.forge/refactor-backlog.yml`.
+
+## Step 3: Sync Framework-Owned Files
+
+For each framework-owned file in the source template:
+
+1. Read the source file content
+2. Read the local file content (if it exists)
+3. If different → overwrite local with source, report as **updated**
+4. If same → report as **unchanged**
+5. If source has a new file not in local → copy it, report as **added**
+6. If local has a file not in source → report as **removed from template** (don't delete — let user decide)
+
+## Step 4: Sync Template-Only Files
+
+Same process as Step 3, but for `.forge/templates/**`.
+
+## Step 5: Handle Merge-Owned Files
+
+For `CLAUDE.md`:
+1. Read source and local versions
+2. If different → **do not overwrite**. Instead, summarize what changed in prose (new sections, removed sections, modified text)
+3. Present the summary to the user and let them decide how to merge
+
+For `.claude/settings.json`:
+1. Read source and local versions
+2. Compare the `forge.*` keys only
+3. If forge keys differ → update only `forge.*` keys in local, preserve user's `hooks` and any other custom keys
+4. Update `forge.version` to match the source package version
+
+## Step 6: Report
+
+Present a summary:
+
+```
+Forge Local Sync Complete
+─────────────────────────
+Source: {path}
+Version: {old} → {new}
+
+Updated: {N} files
+  - .claude/skills/executing/SKILL.md
+  - ...
+
+Added: {N} files
+  - .claude/skills/new-skill/SKILL.md
+  - ...
+
+Removed from template: {N} files
+  - .claude/agents/old-agent.md (still in your project)
+  - ...
+
+Needs manual review: {N} files
+  - CLAUDE.md (new sections: "Upgrade Mechanism", modified: "Skill Routing")
+  - ...
+
+Unchanged: {N} files
+```

package/template/CLAUDE.md

@@ -46,6 +46,7 @@ Forge auto-detects complexity. Override with: "Use Quick/Standard/Full tier."
 | Build UI with design system consistency | `designing` | When UI involved |
 | Review security before shipping | `securing` | When auth/data/API involved |
 | Debug systematically with hypotheses | `debugging` | When stuck |
+| Upgrade Forge framework files | `upgrading` | On-demand |
 | Use Beads for cross-session memory | `beads-integration` | When Beads installed |
 
 ## Context Engineering