forge-orkes 0.3.4 → 0.3.6

package/bin/create-forge.js

@@ -8,6 +8,11 @@ const templateDir = path.join(__dirname, '..', 'template');
 const targetDir = process.cwd();
 const pkgVersion = require('../package.json').version;
 
+// --- Section markers for CLAUDE.md ---
+
+const FORGE_START = '<!-- forge:start -->';
+const FORGE_END = '<!-- forge:end -->';
+
 // --- File classification for upgrades ---
 
 // Framework-owned: Forge controls these entirely
@@ -16,9 +21,6 @@ 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';
 
@@ -128,27 +130,62 @@ function upgradeDir(relDir) {
 }
 
 /**
- * Handle merge-owned files: stage new version for manual review if different.
+ * Smart-merge CLAUDE.md using section markers.
+ * - If markers exist: replace the forge section, preserve everything else
+ * - If no markers but forge content exists: replace it and add markers
+ * - If no forge content: append with markers
+ * Returns 'replaced' | 'appended' | 'unchanged' | 'created'
  */
-function handleMergeFile(relFile) {
-  const srcPath = path.join(templateDir, relFile);
-  const destPath = path.join(targetDir, relFile);
+function mergeClaudeMd() {
+  const srcPath = path.join(templateDir, 'CLAUDE.md');
+  const destPath = path.join(targetDir, 'CLAUDE.md');
 
   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');
+  const forgeContent = fs.readFileSync(srcPath, 'utf-8');
+
+  // No existing CLAUDE.md — just copy
+  if (!fs.existsSync(destPath)) {
+    fs.writeFileSync(destPath, forgeContent);
+    return 'created';
+  }
+
+  const existing = fs.readFileSync(destPath, 'utf-8');
 
-  if (srcContent === destContent) return 'unchanged';
+  // Check if content is already identical
+  if (existing === forgeContent) 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';
+  const startIdx = existing.indexOf(FORGE_START);
+  const endIdx = existing.indexOf(FORGE_END);
+
+  if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+    // Markers found — replace the section between them (inclusive)
+    const before = existing.substring(0, startIdx);
+    const after = existing.substring(endIdx + FORGE_END.length);
+    const merged = before + forgeContent + after;
+
+    // Clean up any double newlines at the seams
+    const cleaned = merged.replace(/\n{3,}/g, '\n\n');
+    fs.writeFileSync(destPath, cleaned);
+    return 'replaced';
+  }
+
+  // No markers — check if there's an old forge section (starts with "# Forge")
+  const forgeHeaderIdx = existing.indexOf('# Forge\n');
+  if (forgeHeaderIdx !== -1) {
+    // Old install without markers — replace from "# Forge" to end of file
+    // (Forge content is always appended at the end in old installs)
+    const before = existing.substring(0, forgeHeaderIdx);
+    const merged = before + forgeContent;
+    const cleaned = merged.replace(/\n{3,}/g, '\n\n');
+    fs.writeFileSync(destPath, cleaned);
+    return 'replaced';
+  }
+
+  // No forge content at all — append with markers
+  const merged = existing.trimEnd() + '\n\n' + forgeContent + '\n';
+  fs.writeFileSync(destPath, merged);
+  return 'appended';
 }
 
 /**
@@ -178,49 +215,40 @@ function upgradeSettings() {
   return 'updated';
 }
 
+/**
+ * Detect if Forge is already installed in this project.
+ */
+function isForgeInstalled() {
+  const settingsPath = path.join(targetDir, SETTINGS_FILE);
+  if (!fs.existsSync(settingsPath)) return false;
+
+  try {
+    const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+    return !!settings.forge;
+  } catch {
+    return false;
+  }
+}
+
 // --- Commands ---
 
 async function install() {
   console.log('\n  Forge - Meta-prompting framework for Claude Code\n');
 
-  // Handle CLAUDE.md
-  const srcClaudeMd = path.join(templateDir, 'CLAUDE.md');
-  const destClaudeMd = path.join(targetDir, 'CLAUDE.md');
-  let claudeMdAction = 'copy';
-
-  if (fs.existsSync(destClaudeMd)) {
-    console.log('  CLAUDE.md already exists in this directory.\n');
-    const answer = await prompt(
-      '  What would you like to do? (a)ppend / (r)eplace / (s)kip: '
-    );
-
-    if (answer === 'a' || answer === 'append') {
-      claudeMdAction = 'append';
-    } else if (answer === 'r' || answer === 'replace') {
-      claudeMdAction = 'replace';
-    } else {
-      claudeMdAction = 'skip';
-    }
-  }
-
-  const srcContent = fs.readFileSync(srcClaudeMd, 'utf-8');
-
-  switch (claudeMdAction) {
-    case 'copy':
-    case 'replace':
-      fs.writeFileSync(destClaudeMd, srcContent);
-      console.log(
-        `  ${claudeMdAction === 'replace' ? 'Replaced' : 'Created'} CLAUDE.md`
-      );
+  // Handle CLAUDE.md — use smart merge
+  const claudeStatus = mergeClaudeMd();
+  switch (claudeStatus) {
+    case 'created':
+      console.log('  Created CLAUDE.md');
+      break;
+    case 'replaced':
+      console.log('  Updated Forge section in CLAUDE.md (user content preserved)');
       break;
-    case 'append': {
-      const existing = fs.readFileSync(destClaudeMd, 'utf-8');
-      fs.writeFileSync(destClaudeMd, existing + '\n\n' + srcContent);
+    case 'appended':
       console.log('  Appended Forge config to existing CLAUDE.md');
       break;
-    }
-    case 'skip':
-      console.log('  Skipped CLAUDE.md');
+    case 'unchanged':
+      console.log('  CLAUDE.md already up to date');
       break;
   }
 
@@ -274,7 +302,6 @@ async function upgrade() {
     added: [],
     unchanged: [],
     removed: [],
-    needsReview: [],
   };
 
   // 1. Process framework-owned directories
@@ -295,14 +322,14 @@ async function upgrade() {
     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);
-    }
+  // 3. Smart-merge CLAUDE.md using section markers
+  const claudeStatus = mergeClaudeMd();
+  if (claudeStatus === 'replaced' || claudeStatus === 'appended') {
+    results.updated.push('CLAUDE.md');
+  } else if (claudeStatus === 'unchanged') {
+    results.unchanged.push('CLAUDE.md');
+  } else if (claudeStatus === 'created') {
+    results.added.push('CLAUDE.md');
   }
 
   // 4. Smart-merge settings.json
@@ -314,8 +341,7 @@ async function upgrade() {
   }
 
   // Report results
-  const totalChanges =
-    results.updated.length + results.added.length + results.needsReview.length;
+  const totalChanges = results.updated.length + results.added.length;
 
   if (totalChanges === 0 && results.removed.length === 0) {
     console.log('  Already up to date.\n');
@@ -338,14 +364,6 @@ async function upgrade() {
     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) {
@@ -366,6 +384,13 @@ if (subcommand === 'upgrade') {
     console.error('Error:', err.message);
     process.exit(1);
   });
+} else if (isForgeInstalled()) {
+  // Auto-detect: Forge already installed, run upgrade instead
+  console.log('  Forge detected — running upgrade automatically.\n');
+  upgrade().catch((err) => {
+    console.error('Error:', err.message);
+    process.exit(1);
+  });
 } else {
   install().catch((err) => {
     console.error('Error:', err.message);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "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/executing/SKILL.md

@@ -42,22 +42,63 @@ After 3 auto-fix attempts on a single task → STOP fixing. Document remaining i
 ### Scope Boundary
 Only fix issues DIRECTLY caused by the current task. Pre-existing warnings, tech debt, unrelated bugs → log to `.forge/deferred-issues.md`, don't fix.
 
+## Native Task Tracking (Hybrid Approach)
+
+Use Claude Code's native task tools (`TaskCreate`, `TaskUpdate`, `TaskList`) for **in-session visibility** during execution. The `.forge/state/milestone-{id}.yml` remains the **cross-session source of truth** — native tasks are a UI layer on top.
+
+### On Plan Start
+
+After loading the plan file, create native tasks from the XML task blocks:
+
+1. Parse all `<task>` XML blocks from the plan
+2. For each task, call `TaskCreate`:
+   - `subject`: The task's `<name>` value
+   - `description`: Combine `<action>`, `<verify>`, and `<done>` fields
+   - `activeForm`: Present-continuous form of the task name (e.g., "Implementing login form")
+3. If the plan has ordered tasks (task 2 depends on task 1), set dependencies via `TaskUpdate` with `addBlockedBy`
+4. Store the mapping: native task ID → plan task number (track mentally or in first task's metadata)
+
+### On Task Start
+
+Before implementing each task:
+1. Call `TaskUpdate` with `status: "in_progress"` on the current native task
+2. This gives the user a visible spinner with the `activeForm` text
+
+### On Task Complete
+
+After each task's commit:
+1. Call `TaskUpdate` with `status: "completed"` on the finished native task
+2. The next task automatically becomes unblocked (if dependencies were set)
+
+### On Plan Complete
+
+Native tasks are session-scoped — they disappear on `/clear` or session end. No cleanup needed. The authoritative state has already been written to `.forge/state/milestone-{id}.yml`.
+
+### When NOT to Create Native Tasks
+
+- **Spawned fresh agents**: Subagents don't share the parent's task list. The parent agent creates the native tasks; the subagent just does the work.
+- **Single-task plans**: If the plan has only 1 task, skip native task creation — the overhead isn't worth it.
+
+---
+
 ## Task Execution Flow
 
 For each task in the plan:
 
 1. **Read** the task XML (name, files, action, verify, done)
-2. **Check** context.md — does this task touch a locked decision? Honor it exactly.
-3. **Implement** following the action instructions
-4. **Verify** using the verify step (run tests, inspect output)
-5. **Confirm** done criteria are met
-6. **Commit** atomically
+2. **Mark in-progress** — `TaskUpdate` the native task to `in_progress`
+3. **Check** context.md — does this task touch a locked decision? Honor it exactly.
+4. **Implement** following the action instructions
+5. **Verify** using the verify step (run tests, inspect output)
+6. **Confirm** done criteria are met
+7. **Commit** atomically
+8. **Mark complete** — `TaskUpdate` the native task to `completed`
 
 ## TDD Flow (When task type="tdd")
 
 ### With Test Spec (from planning Step 7)
 When the task has a `<spec>` field, test specs already exist:
-1. **Copy spec to test location:** Move from `.forge/phases/` to the project's test directory
+1. **Copy spec to test location:** Move from `.forge/phases/m{M}-{N}-{name}/specs/` to the project's test directory
 2. **RED:** Remove `skip` markers from the first test. Confirm it fails. Commit: `test({scope}): activate spec tests for {feature}`
 3. **GREEN:** Write minimal code to make it pass. Repeat for each test in the spec.
 4. **REFACTOR:** Clean up. Commit: `feat({scope}): implement {feature}`
@@ -112,7 +153,7 @@ After each task, mentally assess context usage:
 After completing all tasks in a plan, create a summary:
 
 ```markdown
-# Execution Summary: Phase {N}, Plan {NN}
+# Execution Summary: m{M}-{N}-{name}, Plan {NN}
 
 ## Completed Tasks
 1. [Task name] — [one-line result]

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

@@ -498,22 +498,24 @@ If user explicitly says "Use Quick/Standard/Full tier" — honor it. No argument
 
 ## Step 3: Route to Next Skill
 
-Based on detected tier and current state, tell the user which skill comes next and invoke it.
+Based on detected tier and current state, tell the user which skill comes next and **invoke it using the `Skill` tool**.
+
+**CRITICAL: NEVER use `EnterPlanMode` or Claude Code's native plan mode.** All Forge phases are handled by Forge skills invoked via the `Skill` tool. When the workflow says "planning", that means invoke `Skill(planning)` — not enter native plan mode. Native plan mode writes to a different file format and bypasses Forge's constitutional gates, state management, and structured plan output.
 
 If resuming mid-workflow:
 - Read the selected milestone's state file (`.forge/state/milestone-{id}.yml`) for current position
 - **Use `current.status` to determine the next skill** — this is the authoritative workflow position:
 
-| `current.status` | Next Action |
+| `current.status` | Next Action (invoke via `Skill` tool) |
 |-------------------|-------------|
 | `not_started` | Detect tier, start workflow |
-| `researching` | Resume or complete `researching`, then → `discussing` |
-| `discussing` | Resume or complete `discussing`, then → `planning` (or `architecting` for Full) |
-| `planning` | Resume or complete `planning`, then → `executing` |
-| `executing` | Resume or complete `executing`, then → `verifying` |
-| `verifying` | Resume or complete `verifying`, then → `auditing` |
-| `auditing` | Resume or complete `auditing`, then → `refactoring` |
-| `refactoring` | Resume or complete `refactoring`, then → `complete` |
+| `researching` | Invoke `Skill(researching)`, then → `discussing` |
+| `discussing` | Invoke `Skill(discussing)`, then → `planning` (or `architecting` for Full) |
+| `planning` | Invoke `Skill(planning)`, then → `executing` |
+| `executing` | Invoke `Skill(executing)`, then → `verifying` |
+| `verifying` | Invoke `Skill(verifying)`, then → `auditing` |
+| `auditing` | Invoke `Skill(auditing)`, then → `refactoring` |
+| `refactoring` | Invoke `Skill(refactoring)`, then → `complete` |
 | `complete` | Milestone is done. Ask user what's next. |
 
 - **Never treat a milestone as complete just because `overall_percent` is 100%.** Task completion and workflow completion are different. All planned tasks being done (100%) means execution is finished — verification, auditing, and refactoring still need to run.
@@ -581,7 +583,7 @@ Each skill ends with a standard handoff message. The pattern is:
 | researching | Research summary (markdown in conversation or `.forge/` files) | discussing reads research findings |
 | discussing | Decision summary → carried into planning via context.md | planning reads context.md |
 | architecting | ADRs in `.forge/decisions/`, data models, API contracts | planning reads decisions |
-| planning | Plans in `.forge/phases/`, requirements.yml, roadmap.yml, context.md | executing reads plans |
+| planning | Plans in `.forge/phases/m{M}-{N}-{name}/`, requirements.yml, roadmap.yml, context.md | executing reads plans |
 | executing | Committed code, execution summary, milestone state updated | verifying reads must_haves from plans |
 | verifying | Verification report, desire paths updated | auditing reads project.yml + source files |
 | auditing | Health report in `.forge/audits/` | refactoring reads health report + git diff |

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

@@ -7,6 +7,8 @@ description: "Use when you need to break work into executable tasks with verific
 
 Turn research and requirements into executable, verifiable plans.
 
+> **IMPORTANT:** This skill replaces Claude Code's native plan mode. Do NOT use `EnterPlanMode` — all planning output goes to `.forge/phases/` as structured plan files, not to the native plan file. Follow the steps below directly in the conversation.
+
 ## Step 1: Resolution Gate
 
 Read `.forge/context.md`. Check the **Needs Resolution** section.

package/template/CLAUDE.md

@@ -1,11 +1,18 @@
+<!-- forge:start -->
 # Forge
 
 A lean meta-prompting framework for Claude Code. Synthesizes context engineering (GSD) and constitutional governance (Spec-Kit) on Claude Code's native primitives.
 
+## Critical: No Native Plan Mode
+
+**NEVER use the `EnterPlanMode` tool when the Forge framework is active** (i.e., when `.forge/` exists or a Forge skill is running). Forge has its own `planning` skill that writes structured plans to `.forge/phases/`. Claude Code's native plan mode writes to a separate plan file with a different format — this conflicts with Forge's workflow and state management.
+
+When the workflow reaches the planning phase, **invoke the `planning` skill using the `Skill` tool** — do not enter native plan mode. This applies to all tiers (Standard and Full). The same rule applies to all other Forge phases: always invoke the corresponding Forge skill, never substitute a native Claude Code behavior.
+
 ## Core Principles
 
 1. **Lean by default, powerful when needed.** Quick fixes skip ceremony. Complex features get full governance. The framework adapts — you don't.
-2. **Native-first.** Skills, agents, hooks, plugins — use Claude Code's built-in systems. No custom JavaScript, no reinvented orchestration.
+2. **Native-first.** Skills, agents, hooks, plugins — use Claude Code's built-in systems. No custom JavaScript, no reinvented orchestration. Periodically audit Forge features against Claude Code's current native capabilities — if a native tool now handles what a Forge feature does, deprecate the Forge version. Use native tools for session-scoped concerns (task UI, exploration) and Forge state for cross-session persistence. When in doubt, prefer native.
 3. **Context is sacred.** Every token earns its place. Size-gate all artifacts, lazy-load skills, spawn fresh agents for isolated work.
 4. **Decisions are contracts.** User decisions lock before building begins. Downstream agents honor contracts or flag violations — never silently override.
 5. **Verify against goals, not tasks.** "Does it work?" beats "Did we complete the checklist?" Goal-backward verification at every tier.
@@ -155,3 +162,4 @@ Every task gets its own commit. Format: `{type}({scope}): {description}`
 Types: `feat`, `fix`, `test`, `refactor`, `chore`, `docs`
 Scope: phase-plan or feature area
 Never use `git add .` or `git add -A` — stage files individually.
+<!-- forge:end -->