forge-orkes 0.3.5 → 0.3.7

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.5",
+  "version": "0.3.7",
   "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/forge/SKILL.md

@@ -30,12 +30,11 @@ Check for state files in this order:
 5. **If no active milestones:** Proceed to init or ask user to create one.
 6. Load the selected milestone's state file (`.forge/state/milestone-{id}.yml`)
 7. **Route based on `current.status`, NOT on `overall_percent`.** The `current.status` field is the authoritative workflow position. A milestone is only complete when `current.status` equals `complete`. Even if `overall_percent` is 100%, the milestone still needs to go through any remaining workflow steps (verifying, auditing, refactoring) before it is truly done.
-8. Report position from the milestone-specific state:
+8. Report position briefly, then **immediately route to the next skill** (see Step 3: Mandatory Auto-Routing):
    - **Workflow status** (`current.status`) — this is the primary indicator of where you are
-   - Current phase, plan, task
+   - Phase progress using precise terminology: "Executed" (code done, not verified), "Verified", "Pending", "In progress" — **never say "Complete" for a phase that hasn't been verified**
    - Task progress percentage (`overall_percent`) — this measures task completion, not workflow completion
-   - Active blockers
-   - Recent decisions
+   - **Do NOT present a menu of options.** State the position, state the next action, invoke the skill.
 
 If Beads is installed and enabled (`settings.json → forge.beads_integration: true`), also run `bd prime` for cross-session context. See `beads-integration` skill for details. This is optional — Forge works fully without it.
 
@@ -61,393 +60,7 @@ If state exists → go to **Step 2B: Detect Tier**.
 
 ## Step 2A: Project Init
 
-This interactive workflow runs once when Forge doesn't find an existing project. First, detect whether this is a **brownfield** (existing codebase) or **greenfield** (new project) — then run the appropriate init path.
-
-### Detect Project Type
-
-Check for signals of an existing codebase:
-
-```
-Check: package.json OR requirements.txt OR go.mod OR Cargo.toml (dependency manifest)
-Check: .git/ (version control history)
-Check: src/ OR app/ OR lib/ (source directories)
-Check: existing config files (tsconfig.json, .eslintrc, vite.config, etc.)
-```
-
-- **2+ signals found** → **Brownfield path** (existing codebase)
-- **0-1 signals** → **Greenfield path** (new project)
-
-Ask user to confirm: *"This looks like an [existing project / new project]. Is that right?"*
-
----
-
-### Brownfield Path: Discover Existing Project
-
-For existing codebases, **scan first, confirm with user second.** Don't ask the user to describe what you can discover.
-
-#### Discovery Step 0: Framework Detection
-
-Before scanning the tech stack, check for two things: (1) existing meta-prompting frameworks with project knowledge to absorb, and (2) companion tools that should be preserved alongside Forge.
-
-**Meta-Framework Signatures** (contain project knowledge — candidates for absorption):
-
-```
-# GSD (Get Shit Done)
-Check: agents/gsd-*.md OR commands/gsd/ directory
-Check: Root-level PROJECT.md + REQUIREMENTS.md + ROADMAP.md + STATE.md
-Check: get-shit-done/ directory
-Check: CONTEXT.md with "NON-NEGOTIABLE" or "DEFERRED" sections
-
-# Spec-Kit
-Check: spec-driven.md
-Check: templates/ with spec-template.md
-Check: extensions/catalog.json
-Check: constitution-template.md
-
-# BMAD
-Check: agents/ with 20+ agent files
-Check: workflows/ directory
-Check: bmad-* prefixed files
-
-# Generic / Unknown
-Check: .claude/agents/ or .claude/skills/ (someone else's custom framework)
-Check: CLAUDE.md with framework-like routing tables
-Check: Any structured agent/workflow system
-```
-
-**Companion Tool Signatures** (not frameworks — independent tools that work alongside Forge):
-
-```
-# Beads (persistent cross-session memory)
-Check: .beads/ directory
-Check: beads.jsonl or beads.db
-Check: bd CLI available (Bash: which bd)
-→ If found: Enable forge.beads_integration in settings.json. Do NOT absorb or archive.
-→ Beads is independent — it runs alongside Forge, not inside it.
-```
-
-**If a meta-framework is detected**, present the finding and offer three options:
-
-*"I found an existing [{framework name}] setup in this project. It contains project documentation and decisions that are valuable. How would you like to handle it?"*
-
-**Option A: Absorb & Convert** (recommended)
-Read all existing framework documentation, extract the project knowledge, and convert it into Forge's format. This means:
-- Project descriptions → `.forge/project.yml`
-- Requirements → `.forge/requirements.yml`
-- Roadmaps/plans → `.forge/roadmap.yml`
-- Context/decisions → `.forge/context.md`
-- Current state/progress → `.forge/state/index.yml` + `.forge/state/milestone-{id}.yml`
-- Constitutional rules (if any) → `.forge/constitution.md`
-- Design system rules (if any) → `.forge/design-system.md`
-
-→ Go to **Framework Absorption** below.
-
-**Option B: Archive & Start Fresh**
-Move existing framework files into `.forge/archive/{framework-name}/` for reference, then run the standard brownfield discovery (which will still scan the codebase itself). The archive is preserved and can be consulted later.
-
-**Option C: Keep Both (Transition Period)**
-Initialize Forge alongside the existing framework. Forge reads from `.forge/` while old framework files remain in place. Useful when you want to try Forge without committing. Remove the old framework later when confident.
-
----
-
-#### Framework Absorption (Option A)
-
-When absorbing an existing framework, read its documentation and convert systematically.
-
-**GSD Absorption Map:**
-
-| GSD Source | Read | Extract | Write to Forge |
-|-----------|------|---------|---------------|
-| `PROJECT.md` | Project name, description, tech stack, goals | Structured project info | `.forge/project.yml` |
-| `REQUIREMENTS.md` | Feature requirements, acceptance criteria | Convert prose to YAML with IDs | `.forge/requirements.yml` |
-| `ROADMAP.md` | Phases, milestones, dependencies | Convert to YAML with dependency refs | `.forge/roadmap.yml` |
-| `STATE.md` | Current phase, progress, blockers | Machine-readable state | `.forge/state/index.yml` + `.forge/state/milestone-{id}.yml` |
-| `CONTEXT.md` | NON-NEGOTIABLE decisions, DEFERRED ideas | Locked decisions, deferred items | `.forge/context.md` |
-| `references/ui-brand.md` | Design system rules, brand guidelines | Component mappings, style rules | `.forge/design-system.md` |
-| `references/verification-patterns.md` | Verification approach | Inform `verifying` skill config | Constitution articles |
-| `references/tdd.md` | Testing approach | Inform constitution Article II | Constitution articles |
-| Agent customizations | Custom agent behaviors, tool restrictions | Map to Forge agent definitions | `.claude/agents/*.md` (if custom) |
-
-**Spec-Kit Absorption Map:**
-
-| Spec-Kit Source | Read | Extract | Write to Forge |
-|----------------|------|---------|---------------|
-| `spec-driven.md` | Core methodology | Governance patterns | `.forge/constitution.md` |
-| `templates/spec-template.md` | Spec structure | Requirements format | `.forge/requirements.yml` |
-| `templates/constitution-template.md` | Constitutional articles | Immutable gates | `.forge/constitution.md` |
-| `extensions/` | Extension configs | Specialized skills | `.claude/skills/` (if relevant) |
-| Project specs (if filled in) | Project-specific decisions | Locked decisions | `.forge/context.md` |
-
-**Generic Framework Absorption:**
-
-For unknown frameworks, use the `researching` skill to:
-1. Read all markdown and config files in the framework directory
-2. Identify: project descriptions, requirements, decisions, state, design rules
-3. Map each to the closest Forge equivalent
-4. Present the mapping to the user for confirmation before writing
-
-**Absorption Process:**
-
-1. Read all source files from the existing framework
-2. For each Forge target file, synthesize content from the relevant sources
-3. Convert prose to YAML where Forge expects YAML (project, requirements, roadmap, state)
-4. Preserve markdown where Forge expects markdown (constitution, context, design-system)
-5. **Never discard information** — if something doesn't map to a Forge file, note it in `.forge/context.md` under a "Carried Forward" section
-6. Move original framework files to `.forge/archive/{framework-name}/`
-7. Present a diff-style summary: *"Here's what I converted: [list]. And here's what I archived for reference: [list]. Anything I should handle differently?"*
-
-After absorption, **always** continue with the standard brownfield steps below (tech stack scan, design system detection, etc.). This is critical — see the verification step next.
-
-#### Documentation vs. Codebase Verification
-
-**Never trust framework documentation at face value.** Documentation drifts. The codebase is the source of truth.
-
-After reading existing framework docs, **cross-reference every claim against the actual code**:
-
-```
-For each claim in the documentation:
-  1. Find the corresponding code (Glob, Grep, Read)
-  2. Verify the claim matches reality
-  3. Flag any discrepancies
-```
-
-**Common drift patterns to check:**
-
-| Documentation Says | Verify Against |
-|-------------------|----------------|
-| "Tech stack: React + PostgreSQL" | `package.json` dependencies, actual imports in `src/` |
-| "Uses PrimeReact for all UI" | `Grep: src/ for "from 'primereact"` — are there also raw HTML tables, custom modals? |
-| "Tests written for all features" | `Glob: src/**/*.test.*` — actual coverage vs. claimed coverage |
-| "Auth uses Clerk/Auth0/etc." | `Grep: src/ for auth imports` — is there also custom auth code? |
-| "State management via Redux" | `package.json` + actual imports — did they switch to Zustand mid-project? |
-| "API uses REST" | `Grep: src/ for GraphQL, tRPC, WebSocket` — mixed protocols? |
-| Requirements list features A, B, C | Do routes/components for A, B, C actually exist? Are any partially implemented? |
-| Roadmap says "Phase 2 complete" | Are Phase 2 features actually wired and working, or are there stubs? |
-
-**When discrepancies are found:**
-
-Present them to the user clearly:
-
-*"I found some differences between the GSD documentation and the actual codebase:*
-
-- *PROJECT.md says 'PostgreSQL' but I only see SQLite in dependencies*
-- *REQUIREMENTS.md lists a 'notifications' feature but I can't find any notification code*
-- *STATE.md says Phase 2 is complete, but the dashboard component looks like a stub (returns placeholder text)*
-- *The docs mention PrimeReact exclusively, but I found 3 files using raw HTML tables instead of DataTable*
-
-*Should I update the Forge config to match what's actually in the code, or are some of these features that were removed/deferred?"*
-
-**Priority order for truth:**
-1. **What the code actually does** — highest authority
-2. **What the user confirms** — resolves ambiguity
-3. **What the documentation says** — useful context, but may be stale
-
-Write the verified state to Forge files. For any unresolved discrepancies, add them to `.forge/context.md` under a "Needs Resolution" section so they get addressed during planning.
-
----
-
-#### Discovery Step 1: Tech Stack Scan
-
-```bash
-# Package manifest
-Read: package.json → name, dependencies, devDependencies, scripts
-# Or: requirements.txt, go.mod, Cargo.toml, etc.
-
-# Config files
-Glob: tsconfig.json, .eslintrc*, vite.config.*, next.config.*, webpack.config.*
-Glob: .env.example, docker-compose.yml
-
-# Source structure
-Bash: find src/ -type f | head -50  # understand file organization
-Bash: wc -l src/**/*.{ts,tsx,js,jsx} 2>/dev/null | tail -1  # codebase size
-```
-
-From this, auto-detect:
-- Language and framework
-- Build tools and test framework
-- Database (from dependencies or config)
-- Project name and description (from package.json or README)
-
-#### Discovery Step 2: Design System Detection
-
-```bash
-# Check dependencies for known UI libraries
-Grep: package.json for: primereact, @mui/, @chakra-ui/, @radix-ui/, antd, @headlessui/
-Grep: package.json for: tailwindcss, primeflex, @emotion/, styled-components
-
-# Check actual usage in source
-Grep: src/ for import patterns: "from 'primereact", "from '@mui/", "from '@/components/ui"
-Grep: src/ for icon usage: "pi pi-", "Material", "lucide-react"
-
-# Check for theme files
-Glob: **/*theme*, **/*variables.scss, **/tailwind.config*, **/globals.css
-```
-
-From this, auto-detect:
-- Component library (and version from package.json)
-- Icon set in use
-- Layout system (PrimeFlex, Tailwind, MUI Grid, etc.)
-- Theme approach (SCSS variables, CSS-in-JS, Tailwind config, design tokens)
-
-#### Discovery Step 3: Pattern Analysis
-
-```bash
-# Existing conventions
-Glob: src/**/*.test.* OR src/**/*.spec.*  # test patterns
-Grep: src/ for error handling patterns
-Grep: src/ for auth/session patterns
-Bash: git log --oneline -20  # commit style
-
-# Architecture patterns
-Bash: ls -la src/  # top-level structure (pages, components, services, etc.)
-Glob: src/**/index.{ts,tsx,js}  # barrel exports
-Grep: src/ for "import.*from.*@/"  # path aliases
-```
-
-#### Discovery Step 4: Present Findings
-
-Present a structured summary to the user:
-
-*"I've scanned your codebase. Here's what I found:*
-
-*Project: {name} — {description from README or package.json}*
-*Stack: {language} + {framework} + {database}*
-*UI: {component library} with {icon set}, layout via {layout system}*
-*Testing: {test framework}, {X} existing test files*
-*Size: ~{N} source files, ~{N}K lines*
-*Patterns: {commit style}, {folder structure approach}, {key conventions}*
-
-*Does this look right? Anything I missed or got wrong?"*
-
-#### Discovery Step 5: Design System Mapping
-
-If a component library was detected:
-1. Check `.forge/templates/design-systems/` for an existing example config
-2. If found (e.g., PrimeReact) → copy it as starting point for `.forge/design-system.md`
-3. If not found → use `researching` skill to build a component mapping from docs
-4. **Cross-reference with actual usage**: scan the codebase for which components are already in use and prioritize those in the mapping
-5. Present mapping to user for validation
-
-If no component library detected but UI files exist:
-- Ask: *"I see UI code but no component library. Are you using a design system, or is this custom HTML/CSS?"*
-
-#### Discovery Step 6: Constitutional Inference
-
-Based on discovered patterns, **suggest** which articles to enable:
-
-| Discovery | Suggested Articles |
-|-----------|-------------------|
-| Test files found | Article II: Test-First (already practicing) |
-| Component library detected | Article V: Design System Fidelity |
-| Auth/session patterns found | Article VI: Security by Default |
-| Established conventions detected | Article IV: Consistency (preserve them) |
-| package-lock.json or yarn.lock | Article I: Library-First (already using libraries) |
-| Logging/monitoring deps | Article IX: Observability |
-
-Present grouped recommendations and let user confirm, add, or remove articles.
-
----
-
-### Greenfield Path: Build from Description
-
-For new projects, ask the user to describe what they're building.
-
-#### Greenfield Step 1: Project Basics
-
-Ask the user to describe the project. From their description, fill in `.forge/project.yml`:
-
-- Project name and description
-- Primary goal
-- Tech stack (language, framework, database, testing)
-- Time and scope constraints
-- Success criteria
-- Known risks
-
-Present a summary: *"Does this capture your project correctly? Anything to add or change?"*
-
-#### Greenfield Step 2: Design System Setup
-
-Ask: *"Does this project use a UI component library or design system?"*
-
-**If yes**, ask which one and configure `design_system` in `project.yml`:
-
-```yaml
-design_system:
-  library: ""           # e.g., PrimeReact, Material-UI, shadcn/ui, Ant Design, Chakra UI
-  version: ""           # e.g., 10.x, 5.x
-  icon_set: ""          # e.g., PrimeIcons, Material Icons, Lucide, none
-  layout_system: ""     # e.g., PrimeFlex, MUI Grid, Tailwind, CSS Grid
-  theme_approach: ""    # e.g., SCSS variables, CSS-in-JS, Tailwind config, design tokens
-  docs_url: ""          # e.g., https://primereact.org/datatable/
-```
-
-Then:
-1. Check `.forge/templates/design-systems/` for a starter config
-2. If found → copy and customize for the project
-3. If not → use `researching` skill to build a component mapping from docs
-4. Write the mapping to `.forge/design-system.md`
-
-**If no** (plain HTML/CSS, utility-only, or non-UI project):
-- Set `design_system.library: none` in project.yml
-- Skip design-system.md creation
-- Disable Article V in the constitution
-
-#### Greenfield Step 3: Constitutional Setup
-
-Present the 9 constitutional articles grouped by domain:
-
-**Code quality** (recommended for most projects):
-- Article I: Library-First — prefer proven libraries over custom code
-- Article II: Test-First — tests before or alongside implementation
-- Article III: Simplicity — simplest solution wins
-- Article IV: Consistency — follow existing project patterns
-
-**Design & UI** (enable if project has UI):
-- Article V: Design System Fidelity — use the design system, don't fight it
-
-**Security & data** (enable if auth, user data, or APIs involved):
-- Article VI: Security by Default — auth, validation, secrets are requirements
-
-**Architecture** (enable based on project complexity):
-- Article VII: Integration-First — real dependencies before mocks
-- Article VIII: Documentation-Driven — decisions documented where code lives
-- Article IX: Observability — logging, error reporting, health checks
-
-Ask: *"Which of these articles apply? I'd recommend [suggest based on stack and project type]. You can also add project-specific articles."*
-
----
-
-### Finalize Init (Both Paths)
-
-1. Write `.forge/project.yml` with all gathered/discovered info
-2. Write `.forge/constitution.md` with selected articles
-3. Write `.forge/design-system.md` (if design system configured)
-4. Initialize milestone-aware state:
-   - Create `.forge/state/` directory
-   - Write `.forge/state/index.yml`:
-     ```yaml
-     milestones:
-       - id: 1
-         name: "{project name}"
-         status: active
-         last_updated: "{date}"
-     ```
-   - Write `.forge/state/milestone-1.yml`:
-     ```yaml
-     milestone:
-       id: 1
-       name: "{project name}"
-     current:
-       tier: null
-       phase: null
-       phase_name: ""
-       plan: null
-       task: null
-       status: not_started
-     ```
-5. Copy remaining templates as needed
-
-Confirm: *"Project initialized. Here's what's set up: [summary]. Ready to start working?"*
+If no `.forge/project.yml` exists, invoke the `initializing` skill via `Skill(initializing)`. It handles brownfield/greenfield detection, framework absorption, tech stack scanning, design system setup, and constitutional configuration. After init completes, return here for tier detection.
 
 ## Step 2B: Detect Tier
 
@@ -502,9 +115,23 @@ Based on detected tier and current state, tell the user which skill comes next a
 
 **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:
+### Mandatory Auto-Routing on Resume
+
+**When resuming mid-workflow, DO NOT present a menu of options or ask "What would you like to do?".** Routing is deterministic. Give a brief status briefing, then route automatically. The only time to ask the user for a choice is when `current.status == complete` (milestone done) or when state is ambiguous/corrupted.
+
+Resume steps:
+1. Read the selected milestone's state file (`.forge/state/milestone-{id}.yml`) for current position
+2. **Check for status advancement** (see below)
+3. **Use `current.status` to determine the next skill** — this is the authoritative workflow position
+4. **Brief the user, then route.** Show a compact status summary so the user can orient, then immediately invoke the next skill. Format:
+
+*"Resuming Milestone {id}: {name}*
+*Workflow: {current.status} — next step: {next skill name}*
+*Phases: {compact phase list with statuses using correct wording — Executed/Verified/Pending/In progress}*
+*Progress: {overall_percent}% of tasks executed*
+*Routing to {skill}..."*
+
+This is a **briefing, not a prompt** — the user sees where they are and what's happening next. They can interrupt if they want to do something different, but the default is forward motion.
 
 | `current.status` | Next Action (invoke via `Skill` tool) |
 |-------------------|-------------|
@@ -522,6 +149,27 @@ If resuming mid-workflow:
 - Skip completed phases (phases before `current.status`)
 - Resume from current phase
 
+### Status Advancement Check
+
+Sometimes a session ends before the executing skill advances `current.status`. On resume, detect and fix this:
+
+- **If `current.status == executing`**: Check if all phases in the roadmap have been executed (all plans completed, commits made). If YES → advance `current.status` to `verifying` in the state file, then route to verifying. If NO → route to executing for the next unexecuted phase.
+- **If `current.status == verifying`**: Check if verification report exists. If YES and it passed → advance to `auditing`. If NO → route to verifying.
+- **General rule**: If the work for the current status is done but the status wasn't advanced (session ended mid-handoff), advance it now and route to the next skill.
+
+### Phase Status Wording
+
+When reporting phase progress on resume, use precise terminology to avoid confusion:
+
+| Phase State | Display As | Meaning |
+|------------|-----------|---------|
+| All tasks executed, commits made | **"Executed"** | Code is written and committed, but NOT yet verified |
+| Verified by verifying skill | **"Verified"** | Passed goal-backward verification |
+| Not yet started | **"Pending"** | No work done yet |
+| Currently in progress | **"In progress"** | Partially executed |
+
+**Never say a phase is "Complete" unless it has passed through the full workflow** (executed + verified + audited). Use "Executed" for phases where code is done but verification hasn't run. This prevents users from thinking a phase is fully done when it still needs verification.
+
 ### On-Demand Discussion
 
 The `discussing` skill can be invoked at any time, regardless of current workflow position. If the user says "discuss Phase 2", "let's talk through the plan", "I want to rethink this", or similar — route to `discussing` immediately. After the discussion concludes, return to whatever skill was active (or re-plan if the discussion changed direction).

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

@@ -0,0 +1,396 @@
+---
+name: initializing
+description: "Run once per project to detect brownfield/greenfield, scan tech stack, absorb existing frameworks, configure design system, and set up constitutional gates. Invoked by the forge skill when no .forge/project.yml exists."
+---
+
+# Initializing: Project Setup
+
+This interactive workflow runs once when Forge doesn't find an existing project (no `.forge/project.yml`). First, detect whether this is a **brownfield** (existing codebase) or **greenfield** (new project) — then run the appropriate init path.
+
+## Detect Project Type
+
+Check for signals of an existing codebase:
+
+```
+Check: package.json OR requirements.txt OR go.mod OR Cargo.toml (dependency manifest)
+Check: .git/ (version control history)
+Check: src/ OR app/ OR lib/ (source directories)
+Check: existing config files (tsconfig.json, .eslintrc, vite.config, etc.)
+```
+
+- **2+ signals found** → **Brownfield path** (existing codebase)
+- **0-1 signals** → **Greenfield path** (new project)
+
+Ask user to confirm: *"This looks like an [existing project / new project]. Is that right?"*
+
+---
+
+## Brownfield Path: Discover Existing Project
+
+For existing codebases, **scan first, confirm with user second.** Don't ask the user to describe what you can discover.
+
+### Discovery Step 0: Framework Detection
+
+Before scanning the tech stack, check for two things: (1) existing meta-prompting frameworks with project knowledge to absorb, and (2) companion tools that should be preserved alongside Forge.
+
+**Meta-Framework Signatures** (contain project knowledge — candidates for absorption):
+
+```
+# GSD (Get Shit Done)
+Check: agents/gsd-*.md OR commands/gsd/ directory
+Check: Root-level PROJECT.md + REQUIREMENTS.md + ROADMAP.md + STATE.md
+Check: get-shit-done/ directory
+Check: CONTEXT.md with "NON-NEGOTIABLE" or "DEFERRED" sections
+
+# Spec-Kit
+Check: spec-driven.md
+Check: templates/ with spec-template.md
+Check: extensions/catalog.json
+Check: constitution-template.md
+
+# BMAD
+Check: agents/ with 20+ agent files
+Check: workflows/ directory
+Check: bmad-* prefixed files
+
+# Generic / Unknown
+Check: .claude/agents/ or .claude/skills/ (someone else's custom framework)
+Check: CLAUDE.md with framework-like routing tables
+Check: Any structured agent/workflow system
+```
+
+**Companion Tool Signatures** (not frameworks — independent tools that work alongside Forge):
+
+```
+# Beads (persistent cross-session memory)
+Check: .beads/ directory
+Check: beads.jsonl or beads.db
+Check: bd CLI available (Bash: which bd)
+→ If found: Enable forge.beads_integration in settings.json. Do NOT absorb or archive.
+→ Beads is independent — it runs alongside Forge, not inside it.
+```
+
+**If a meta-framework is detected**, present the finding and offer three options:
+
+*"I found an existing [{framework name}] setup in this project. It contains project documentation and decisions that are valuable. How would you like to handle it?"*
+
+**Option A: Absorb & Convert** (recommended)
+Read all existing framework documentation, extract the project knowledge, and convert it into Forge's format. This means:
+- Project descriptions → `.forge/project.yml`
+- Requirements → `.forge/requirements.yml`
+- Roadmaps/plans → `.forge/roadmap.yml`
+- Context/decisions → `.forge/context.md`
+- Current state/progress → `.forge/state/index.yml` + `.forge/state/milestone-{id}.yml`
+- Constitutional rules (if any) → `.forge/constitution.md`
+- Design system rules (if any) → `.forge/design-system.md`
+
+→ Go to **Framework Absorption** below.
+
+**Option B: Archive & Start Fresh**
+Move existing framework files into `.forge/archive/{framework-name}/` for reference, then run the standard brownfield discovery (which will still scan the codebase itself). The archive is preserved and can be consulted later.
+
+**Option C: Keep Both (Transition Period)**
+Initialize Forge alongside the existing framework. Forge reads from `.forge/` while old framework files remain in place. Useful when you want to try Forge without committing. Remove the old framework later when confident.
+
+---
+
+### Framework Absorption (Option A)
+
+When absorbing an existing framework, read its documentation and convert systematically.
+
+**GSD Absorption Map:**
+
+| GSD Source | Read | Extract | Write to Forge |
+|-----------|------|---------|---------------|
+| `PROJECT.md` | Project name, description, tech stack, goals | Structured project info | `.forge/project.yml` |
+| `REQUIREMENTS.md` | Feature requirements, acceptance criteria | Convert prose to YAML with IDs | `.forge/requirements.yml` |
+| `ROADMAP.md` | Phases, milestones, dependencies | Convert to YAML with dependency refs | `.forge/roadmap.yml` |
+| `STATE.md` | Current phase, progress, blockers | Machine-readable state | `.forge/state/index.yml` + `.forge/state/milestone-{id}.yml` |
+| `CONTEXT.md` | NON-NEGOTIABLE decisions, DEFERRED ideas | Locked decisions, deferred items | `.forge/context.md` |
+| `references/ui-brand.md` | Design system rules, brand guidelines | Component mappings, style rules | `.forge/design-system.md` |
+| `references/verification-patterns.md` | Verification approach | Inform `verifying` skill config | Constitution articles |
+| `references/tdd.md` | Testing approach | Inform constitution Article II | Constitution articles |
+| Agent customizations | Custom agent behaviors, tool restrictions | Map to Forge agent definitions | `.claude/agents/*.md` (if custom) |
+
+**Spec-Kit Absorption Map:**
+
+| Spec-Kit Source | Read | Extract | Write to Forge |
+|----------------|------|---------|---------------|
+| `spec-driven.md` | Core methodology | Governance patterns | `.forge/constitution.md` |
+| `templates/spec-template.md` | Spec structure | Requirements format | `.forge/requirements.yml` |
+| `templates/constitution-template.md` | Constitutional articles | Immutable gates | `.forge/constitution.md` |
+| `extensions/` | Extension configs | Specialized skills | `.claude/skills/` (if relevant) |
+| Project specs (if filled in) | Project-specific decisions | Locked decisions | `.forge/context.md` |
+
+**Generic Framework Absorption:**
+
+For unknown frameworks, use the `researching` skill to:
+1. Read all markdown and config files in the framework directory
+2. Identify: project descriptions, requirements, decisions, state, design rules
+3. Map each to the closest Forge equivalent
+4. Present the mapping to the user for confirmation before writing
+
+**Absorption Process:**
+
+1. Read all source files from the existing framework
+2. For each Forge target file, synthesize content from the relevant sources
+3. Convert prose to YAML where Forge expects YAML (project, requirements, roadmap, state)
+4. Preserve markdown where Forge expects markdown (constitution, context, design-system)
+5. **Never discard information** — if something doesn't map to a Forge file, note it in `.forge/context.md` under a "Carried Forward" section
+6. Move original framework files to `.forge/archive/{framework-name}/`
+7. Present a diff-style summary: *"Here's what I converted: [list]. And here's what I archived for reference: [list]. Anything I should handle differently?"*
+
+After absorption, **always** continue with the standard brownfield steps below (tech stack scan, design system detection, etc.). This is critical — see the verification step next.
+
+### Documentation vs. Codebase Verification
+
+**Never trust framework documentation at face value.** Documentation drifts. The codebase is the source of truth.
+
+After reading existing framework docs, **cross-reference every claim against the actual code**:
+
+```
+For each claim in the documentation:
+  1. Find the corresponding code (Glob, Grep, Read)
+  2. Verify the claim matches reality
+  3. Flag any discrepancies
+```
+
+**Common drift patterns to check:**
+
+| Documentation Says | Verify Against |
+|-------------------|----------------|
+| "Tech stack: React + PostgreSQL" | `package.json` dependencies, actual imports in `src/` |
+| "Uses PrimeReact for all UI" | `Grep: src/ for "from 'primereact"` — are there also raw HTML tables, custom modals? |
+| "Tests written for all features" | `Glob: src/**/*.test.*` — actual coverage vs. claimed coverage |
+| "Auth uses Clerk/Auth0/etc." | `Grep: src/ for auth imports` — is there also custom auth code? |
+| "State management via Redux" | `package.json` + actual imports — did they switch to Zustand mid-project? |
+| "API uses REST" | `Grep: src/ for GraphQL, tRPC, WebSocket` — mixed protocols? |
+| Requirements list features A, B, C | Do routes/components for A, B, C actually exist? Are any partially implemented? |
+| Roadmap says "Phase 2 complete" | Are Phase 2 features actually wired and working, or are there stubs? |
+
+**When discrepancies are found:**
+
+Present them to the user clearly:
+
+*"I found some differences between the GSD documentation and the actual codebase:*
+
+- *PROJECT.md says 'PostgreSQL' but I only see SQLite in dependencies*
+- *REQUIREMENTS.md lists a 'notifications' feature but I can't find any notification code*
+- *STATE.md says Phase 2 is complete, but the dashboard component looks like a stub (returns placeholder text)*
+- *The docs mention PrimeReact exclusively, but I found 3 files using raw HTML tables instead of DataTable*
+
+*Should I update the Forge config to match what's actually in the code, or are some of these features that were removed/deferred?"*
+
+**Priority order for truth:**
+1. **What the code actually does** — highest authority
+2. **What the user confirms** — resolves ambiguity
+3. **What the documentation says** — useful context, but may be stale
+
+Write the verified state to Forge files. For any unresolved discrepancies, add them to `.forge/context.md` under a "Needs Resolution" section so they get addressed during planning.
+
+---
+
+### Discovery Step 1: Tech Stack Scan
+
+```bash
+# Package manifest
+Read: package.json → name, dependencies, devDependencies, scripts
+# Or: requirements.txt, go.mod, Cargo.toml, etc.
+
+# Config files
+Glob: tsconfig.json, .eslintrc*, vite.config.*, next.config.*, webpack.config.*
+Glob: .env.example, docker-compose.yml
+
+# Source structure
+Bash: find src/ -type f | head -50  # understand file organization
+Bash: wc -l src/**/*.{ts,tsx,js,jsx} 2>/dev/null | tail -1  # codebase size
+```
+
+From this, auto-detect:
+- Language and framework
+- Build tools and test framework
+- Database (from dependencies or config)
+- Project name and description (from package.json or README)
+
+### Discovery Step 2: Design System Detection
+
+```bash
+# Check dependencies for known UI libraries
+Grep: package.json for: primereact, @mui/, @chakra-ui/, @radix-ui/, antd, @headlessui/
+Grep: package.json for: tailwindcss, primeflex, @emotion/, styled-components
+
+# Check actual usage in source
+Grep: src/ for import patterns: "from 'primereact", "from '@mui/", "from '@/components/ui"
+Grep: src/ for icon usage: "pi pi-", "Material", "lucide-react"
+
+# Check for theme files
+Glob: **/*theme*, **/*variables.scss, **/tailwind.config*, **/globals.css
+```
+
+From this, auto-detect:
+- Component library (and version from package.json)
+- Icon set in use
+- Layout system (PrimeFlex, Tailwind, MUI Grid, etc.)
+- Theme approach (SCSS variables, CSS-in-JS, Tailwind config, design tokens)
+
+### Discovery Step 3: Pattern Analysis
+
+```bash
+# Existing conventions
+Glob: src/**/*.test.* OR src/**/*.spec.*  # test patterns
+Grep: src/ for error handling patterns
+Grep: src/ for auth/session patterns
+Bash: git log --oneline -20  # commit style
+
+# Architecture patterns
+Bash: ls -la src/  # top-level structure (pages, components, services, etc.)
+Glob: src/**/index.{ts,tsx,js}  # barrel exports
+Grep: src/ for "import.*from.*@/"  # path aliases
+```
+
+### Discovery Step 4: Present Findings
+
+Present a structured summary to the user:
+
+*"I've scanned your codebase. Here's what I found:*
+
+*Project: {name} — {description from README or package.json}*
+*Stack: {language} + {framework} + {database}*
+*UI: {component library} with {icon set}, layout via {layout system}*
+*Testing: {test framework}, {X} existing test files*
+*Size: ~{N} source files, ~{N}K lines*
+*Patterns: {commit style}, {folder structure approach}, {key conventions}*
+
+*Does this look right? Anything I missed or got wrong?"*
+
+### Discovery Step 5: Design System Mapping
+
+If a component library was detected:
+1. Check `.forge/templates/design-systems/` for an existing example config
+2. If found (e.g., PrimeReact) → copy it as starting point for `.forge/design-system.md`
+3. If not found → use `researching` skill to build a component mapping from docs
+4. **Cross-reference with actual usage**: scan the codebase for which components are already in use and prioritize those in the mapping
+5. Present mapping to user for validation
+
+If no component library detected but UI files exist:
+- Ask: *"I see UI code but no component library. Are you using a design system, or is this custom HTML/CSS?"*
+
+### Discovery Step 6: Constitutional Inference
+
+Based on discovered patterns, **suggest** which articles to enable:
+
+| Discovery | Suggested Articles |
+|-----------|-------------------|
+| Test files found | Article II: Test-First (already practicing) |
+| Component library detected | Article V: Design System Fidelity |
+| Auth/session patterns found | Article VI: Security by Default |
+| Established conventions detected | Article IV: Consistency (preserve them) |
+| package-lock.json or yarn.lock | Article I: Library-First (already using libraries) |
+| Logging/monitoring deps | Article IX: Observability |
+
+Present grouped recommendations and let user confirm, add, or remove articles.
+
+---
+
+## Greenfield Path: Build from Description
+
+For new projects, ask the user to describe what they're building.
+
+### Greenfield Step 1: Project Basics
+
+Ask the user to describe the project. From their description, fill in `.forge/project.yml`:
+
+- Project name and description
+- Primary goal
+- Tech stack (language, framework, database, testing)
+- Time and scope constraints
+- Success criteria
+- Known risks
+
+Present a summary: *"Does this capture your project correctly? Anything to add or change?"*
+
+### Greenfield Step 2: Design System Setup
+
+Ask: *"Does this project use a UI component library or design system?"*
+
+**If yes**, ask which one and configure `design_system` in `project.yml`:
+
+```yaml
+design_system:
+  library: ""           # e.g., PrimeReact, Material-UI, shadcn/ui, Ant Design, Chakra UI
+  version: ""           # e.g., 10.x, 5.x
+  icon_set: ""          # e.g., PrimeIcons, Material Icons, Lucide, none
+  layout_system: ""     # e.g., PrimeFlex, MUI Grid, Tailwind, CSS Grid
+  theme_approach: ""    # e.g., SCSS variables, CSS-in-JS, Tailwind config, design tokens
+  docs_url: ""          # e.g., https://primereact.org/datatable/
+```
+
+Then:
+1. Check `.forge/templates/design-systems/` for a starter config
+2. If found → copy and customize for the project
+3. If not → use `researching` skill to build a component mapping from docs
+4. Write the mapping to `.forge/design-system.md`
+
+**If no** (plain HTML/CSS, utility-only, or non-UI project):
+- Set `design_system.library: none` in project.yml
+- Skip design-system.md creation
+- Disable Article V in the constitution
+
+### Greenfield Step 3: Constitutional Setup
+
+Present the 9 constitutional articles grouped by domain:
+
+**Code quality** (recommended for most projects):
+- Article I: Library-First — prefer proven libraries over custom code
+- Article II: Test-First — tests before or alongside implementation
+- Article III: Simplicity — simplest solution wins
+- Article IV: Consistency — follow existing project patterns
+
+**Design & UI** (enable if project has UI):
+- Article V: Design System Fidelity — use the design system, don't fight it
+
+**Security & data** (enable if auth, user data, or APIs involved):
+- Article VI: Security by Default — auth, validation, secrets are requirements
+
+**Architecture** (enable based on project complexity):
+- Article VII: Integration-First — real dependencies before mocks
+- Article VIII: Documentation-Driven — decisions documented where code lives
+- Article IX: Observability — logging, error reporting, health checks
+
+Ask: *"Which of these articles apply? I'd recommend [suggest based on stack and project type]. You can also add project-specific articles."*
+
+---
+
+## Finalize Init (Both Paths)
+
+1. Write `.forge/project.yml` with all gathered/discovered info
+2. Write `.forge/constitution.md` with selected articles
+3. Write `.forge/design-system.md` (if design system configured)
+4. Initialize milestone-aware state:
+   - Create `.forge/state/` directory
+   - Write `.forge/state/index.yml`:
+     ```yaml
+     milestones:
+       - id: 1
+         name: "{project name}"
+         status: active
+         last_updated: "{date}"
+     ```
+   - Write `.forge/state/milestone-1.yml`:
+     ```yaml
+     milestone:
+       id: 1
+       name: "{project name}"
+     current:
+       tier: null
+       phase: null
+       phase_name: ""
+       plan: null
+       task: null
+       status: not_started
+     ```
+5. Copy remaining templates as needed
+
+Confirm: *"Project initialized. Here's what's set up: [summary]. Ready to start working?"*
+
+After init completes, return control to the `forge` skill for tier detection and routing.

package/template/CLAUDE.md

@@ -1,3 +1,4 @@
+<!-- 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.
@@ -40,6 +41,7 @@ Forge auto-detects complexity. Override with: "Use Quick/Standard/Full tier."
 | When you need to... | Use skill | Tier |
 |---------------------|-----------|------|
 | Start any task (entry point) | `forge` | All |
+| Set up a new project (brownfield or greenfield) | `initializing` | First run only |
 | Investigate codebase, tech, or requirements | `researching` | Standard, Full |
 | Talk through approach, trade-offs, or revisit a plan | `discussing` | Standard, Full (also on-demand) |
 | Make architectural decisions with rationale | `architecting` | Full |
@@ -161,3 +163,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 -->