buildflow-dev 1.0.1 → 1.0.3

package/src/commands/install.js

@@ -26,6 +26,9 @@ const TOOLS = {
       return hasCli || hasClaudeDir
     },
 
+    isInstalledLocal()  { return existsSync(join(process.cwd(), '.claude', 'commands', 'buildflow-start.md')) },
+    isInstalledGlobal() { return existsSync(join(homedir(), '.claude', 'commands', 'buildflow-start.md')) },
+
     installGlobal(commandFiles) {
       const dir = join(homedir(), '.claude', 'commands')
       mkdirSync(dir, { recursive: true })
@@ -59,6 +62,9 @@ const TOOLS = {
       try { which.sync('gemini'); return true } catch { return false }
     },
 
+    isInstalledLocal()  { return existsSync(join(process.cwd(), '.gemini', 'commands', 'start.md')) },
+    isInstalledGlobal() { return existsSync(join(homedir(), '.gemini', 'commands', 'start.md')) },
+
     installGlobal(commandFiles) {
       const dir = join(homedir(), '.gemini', 'commands')
       mkdirSync(dir, { recursive: true })
@@ -101,27 +107,34 @@ const TOOLS = {
       try { which.sync('codex'); return true } catch { return false }
     },
 
+    isInstalledLocal()  { return existsSync(join(process.cwd(), '.codex', 'instructions', 'buildflow-start.md')) },
+    isInstalledGlobal() { return existsSync(join(homedir(), '.codex', 'instructions', 'buildflow-start.md')) },
+
     installGlobal(commandFiles) {
       const dir = join(homedir(), '.codex', 'instructions')
+      const skillsDir = join(homedir(), '.codex', 'skills')
       mkdirSync(dir, { recursive: true })
       for (const [name, content] of Object.entries(commandFiles)) {
         writeFileSync(join(dir, `buildflow-${name}.md`), content)
+        writeCodexSkill(skillsDir, name, content)
       }
       patchAgentsMd(join(homedir(), '.codex', 'AGENTS.md'), 'global')
-      return dir
+      return `${dir} + ${skillsDir}`
     },
 
     installLocal(commandFiles) {
       const dir = join(process.cwd(), '.codex', 'instructions')
+      const skillsDir = join(process.cwd(), '.codex', 'skills')
       mkdirSync(dir, { recursive: true })
       for (const [name, content] of Object.entries(commandFiles)) {
         writeFileSync(join(dir, `buildflow-${name}.md`), content)
+        writeCodexSkill(skillsDir, name, content)
       }
       patchAgentsMd(join(process.cwd(), 'AGENTS.md'), 'local')
-      return dir
+      return `${dir} + ${skillsDir}`
     },
 
-    triggerNote: 'In Codex CLI, say "use the buildflow-start instructions" or type /buildflow-start',
+    triggerNote: 'In Codex CLI, use $buildflow-start or say "use buildflow-start". Slash menu commands are not exposed by Codex.',
   },
 
   cursor: {
@@ -139,6 +152,9 @@ const TOOLS = {
       return hasCursorApp || hasCursorDir
     },
 
+    isInstalledLocal()  { return existsSync(join(process.cwd(), '.cursor', 'rules', 'buildflow.mdc')) },
+    isInstalledGlobal() { return this.isInstalledLocal() },
+
     installGlobal(commandFiles) {
       return this.installLocal(commandFiles)
     },
@@ -171,6 +187,12 @@ const TOOLS = {
       )
     },
 
+    isInstalledLocal() {
+      const p = join(process.cwd(), '.clinerules')
+      return existsSync(p) && readFileSync(p, 'utf8').includes('BuildFlow')
+    },
+    isInstalledGlobal() { return this.isInstalledLocal() },
+
     installGlobal(commandFiles) {
       return this.installLocal(commandFiles)
     },
@@ -194,6 +216,9 @@ const TOOLS = {
       return existsSync(join(homedir(), '.continue', 'config.json'))
     },
 
+    isInstalledLocal()  { return existsSync(join(process.cwd(), '.continue', 'buildflow', 'start.md')) },
+    isInstalledGlobal() { return existsSync(join(homedir(), '.continue', 'buildflow', 'start.md')) },
+
     installGlobal(commandFiles) {
       const dir = join(homedir(), '.continue', 'buildflow')
       mkdirSync(dir, { recursive: true })
@@ -218,21 +243,58 @@ const TOOLS = {
 
 }
 
+const UPDATE_CHECK_INSTRUCTION = `
+## BuildFlow Update Check (Run Every Session)
+
+At the very start of every session, before anything else:
+1. Check if \`.buildflow/core/UPDATE.md\` exists
+2. If it does, show the user this notice:
+   > "BuildFlow update available — run \`npx buildflow-dev update\` in your terminal to upgrade."
+   Then show the contents of UPDATE.md so the user sees the version details.
+3. If the file does not exist, proceed silently.
+`
+
 function geminiContextBlock(commandFiles) {
   const commandList = Object.keys(commandFiles)
     .map(name => `- \`/buildflow-${name}\`: see .gemini/commands/${name}.md`)
     .join('\n')
-  return `## BuildFlow Commands\n\nWhen the user types a /buildflow-* command, load and execute the corresponding file from .gemini/commands/.\n\n${commandList}`
+  return `## BuildFlow Commands
+
+When the user types a /buildflow-* command, load and execute the corresponding file from .gemini/commands/.
+
+${commandList}
+${UPDATE_CHECK_INSTRUCTION}`
 }
 
 function patchAgentsMd(filePath, scope) {
   const existing = existsSync(filePath) ? readFileSync(filePath, 'utf8') : ''
   if (existing.includes('BuildFlow')) return
   const dir = scope === 'global' ? '~/.codex/instructions/' : '.codex/instructions/'
-  const block = `\n\n## BuildFlow Instructions\n\nWhen the user types /buildflow-<command>, load the matching file from ${dir} and follow those instructions.\n\nAvailable commands: start, think, plan, build, check, ship, onboard, modify, refactor, audit, status, explain, back, help\n`
+  const block = `\n\n## BuildFlow Instructions\n\nWhen the user types $buildflow-<command> or /buildflow-<command>, load the matching file from ${dir} and follow those instructions.\n\nAvailable commands: start, think, plan, build, check, ship, onboard, modify, refactor, audit, status, explain, back, help\n${UPDATE_CHECK_INSTRUCTION}`
   writeFileSync(filePath, existing + block)
 }
 
+function writeCodexSkill(skillsDir, name, commandContent) {
+  const skillName = `buildflow-${name}`
+  const skillDir = join(skillsDir, skillName)
+  mkdirSync(skillDir, { recursive: true })
+  writeFileSync(join(skillDir, 'SKILL.md'), codexSkillContent(skillName, commandContent))
+}
+
+function codexSkillContent(skillName, commandContent) {
+  const description = extractFrontmatterValue(commandContent, 'description') || `Run ${skillName}`
+  return `---\nname: "${skillName}"\ndescription: "${escapeYamlString(description)}"\nmetadata:\n  short-description: "${escapeYamlString(description)}"\n---\n\n<objective>\nExecute the BuildFlow workflow below end-to-end.\nTreat any user text after $${skillName} as arguments for this workflow.\n</objective>\n\n<workflow>\n${commandContent}\n</workflow>\n`
+}
+
+function extractFrontmatterValue(content, key) {
+  const match = content.match(new RegExp(`^${key}:\\s*(.+)$`, 'm'))
+  return match?.[1]?.trim().replace(/^["']|["']$/g, '')
+}
+
+function escapeYamlString(value) {
+  return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')
+}
+
 function cursorRulesContent(commandFiles) {
   const commandDescriptions = Object.keys(commandFiles)
     .map(name => `- @buildflow-${name}`)
@@ -246,7 +308,7 @@ alwaysApply: false
 # BuildFlow v3.0
 
 You are integrated with BuildFlow, an adaptive development orchestration system.
-
+${UPDATE_CHECK_INSTRUCTION}
 ## Available Commands
 
 When the user types @buildflow-<command> or references a buildflow command, execute the corresponding workflow:
@@ -283,7 +345,7 @@ function clineRulesContent(commandFiles) {
     .map(name => `- /buildflow-${name}`)
     .join('\n')
   return `# BuildFlow v3.0 Rules for Cline
-
+${UPDATE_CHECK_INSTRUCTION}
 ## Slash Commands
 
 When the user types any of the following commands, load the corresponding instruction file from .buildflow/commands/:
@@ -359,6 +421,17 @@ function detectAppName() {
   return process.cwd().split(/[/\\]/).pop() || 'my-project'
 }
 
+export function getToolStatus() {
+  return Object.values(TOOLS).map(tool => ({
+    id:              tool.id,
+    name:            tool.name,
+    icon:            tool.icon,
+    detected:        tool.detect(),
+    installedLocal:  tool.isInstalledLocal(),
+    installedGlobal: tool.isInstalledGlobal(),
+  }))
+}
+
 function loadCommandTemplates() {
   const templatesDir = join(__dirname, '../../templates/commands')
   const commands = {}
@@ -393,17 +466,30 @@ export async function run(opts = {}) {
   const detectedList = Object.entries(detected).filter(([, found]) => found)
   const notFoundList = Object.entries(detected).filter(([, found]) => !found)
 
+  // Tools detected on the system but BuildFlow not yet installed into them
+  const newlyDetected = detectedList.filter(([id]) => {
+    const t = TOOLS[id]
+    return !t.isInstalledLocal() && !t.isInstalledGlobal()
+  })
+
   if (detectedList.length > 0) {
     console.log(chalk.green('  ✓ Detected on your system:'))
     for (const [id] of detectedList) {
       const t = TOOLS[id]
-      console.log(chalk.green(`    ${t.icon}  ${t.name}`) + chalk.dim(` — ${t.description}`))
+      const installed = t.isInstalledLocal() || t.isInstalledGlobal()
+      const badge = installed ? chalk.dim(' (already installed)') : chalk.yellow(' (not yet installed)')
+      console.log(chalk.green(`    ${t.icon}  ${t.name}`) + badge)
     }
   } else {
     console.log(chalk.yellow('  ⚠  No AI tools detected automatically.'))
     console.log(chalk.dim('     You can still install for tools not on this list.\n'))
   }
 
+  if (newlyDetected.length > 0) {
+    console.log(chalk.yellow(`\n  ${newlyDetected.length} tool(s) detected but BuildFlow not installed yet.`))
+    console.log(chalk.dim('  They are pre-selected below.\n'))
+  }
+
   if (notFoundList.length > 0) {
     console.log(chalk.dim('\n  Not detected (can still install):'))
     for (const [id] of notFoundList) {
@@ -428,11 +514,19 @@ export async function run(opts = {}) {
       return
     }
   } else {
-    const choices = Object.entries(TOOLS).map(([id, tool]) => ({
-      name: id,
-      message: `${tool.icon}  ${tool.name}${detected[id] ? chalk.green(' ✓') : ''}`,
-      hint: tool.description,
-    }))
+    const choices = Object.entries(TOOLS).map(([id, tool]) => {
+      const isInstalled = tool.isInstalledLocal() || tool.isInstalledGlobal()
+      const statusBadge = !detected[id]
+        ? ''
+        : isInstalled
+          ? chalk.dim(' (reinstall)')
+          : chalk.yellow(' ← new')
+      return {
+        name: id,
+        message: `${tool.icon}  ${tool.name}${statusBadge}`,
+        hint: tool.description,
+      }
+    })
 
     const { tools } = await prompt({
       type: 'multiselect',
@@ -440,7 +534,10 @@ export async function run(opts = {}) {
       message: 'Which AI tools do you want to install BuildFlow into?',
       hint: '(Space to select, Enter to confirm)',
       choices,
-      initial: detectedList.map(([id]) => id),
+      // Pre-select newly detected tools (detected but not yet installed)
+      initial: newlyDetected.length > 0
+        ? newlyDetected.map(([id]) => id)
+        : detectedList.map(([id]) => id),
     })
 
     if (!tools || tools.length === 0) {
@@ -539,9 +636,15 @@ export async function run(opts = {}) {
   if (succeeded.length > 0) {
     console.log(chalk.bold('\n  Next steps:\n'))
     console.log(chalk.white('  1. Open your AI tool in this project'))
-    console.log(chalk.white('  2. Type "/" to see BuildFlow commands'))
-    console.log(chalk.white('  3. Start with: ') + chalk.cyan('/buildflow-start'))
-    console.log(chalk.white('     Or for existing projects: ') + chalk.cyan('/buildflow-onboard'))
+    if (succeeded.every(({ tool }) => tool.id === 'codex')) {
+      console.log(chalk.white('  2. Restart Codex CLI so new skills are loaded'))
+      console.log(chalk.white('  3. Start with: ') + chalk.cyan('$buildflow-start'))
+      console.log(chalk.white('     Or for existing projects: ') + chalk.cyan('$buildflow-onboard'))
+    } else {
+      console.log(chalk.white('  2. Type "/" to see BuildFlow commands'))
+      console.log(chalk.white('  3. Start with: ') + chalk.cyan('/buildflow-start'))
+      console.log(chalk.white('     Or for existing projects: ') + chalk.cyan('/buildflow-onboard'))
+    }
     console.log('')
   }
 }

package/src/commands/status.js

@@ -1,6 +1,7 @@
 import chalk from 'chalk'
 import { existsSync, readFileSync, readdirSync, statSync } from 'fs'
 import { join } from 'path'
+import { getToolStatus } from './install.js'
 
 export async function run(opts = {}) {
   const base = join(process.cwd(), '.buildflow')
@@ -35,10 +36,44 @@ export async function run(opts = {}) {
      onboarded === 'n/a'  ? chalk.dim('N/A (greenfield)') :
                             chalk.yellow('No — run /buildflow-onboard')))
 
-  const hasDebt = debt.includes('## Active') && !debt.includes('[None]')
+  const hasDebt = debt.includes('## Active') && !debt.includes('*None')
   console.log(chalk.dim('  Security debt: ') +
     (hasDebt ? chalk.red('⚠ Issues pending — see .buildflow/security/DEBT.md') : chalk.green('Clean')))
 
+  // ── AI Tool Status ──────────────────────────────────────────────────────────
+  console.log(chalk.dim('\n  AI Tools:\n'))
+
+  const tools = getToolStatus()
+  const uninstalled = []
+
+  for (const t of tools) {
+    if (!t.detected) {
+      console.log(chalk.dim(`    ${t.icon}  ${t.name}`) + chalk.dim('  — not installed on this machine'))
+      continue
+    }
+
+    const local  = t.installedLocal
+    const global = t.installedGlobal
+
+    if (local || global) {
+      const scope = local && global ? 'local + global' : local ? 'local' : 'global'
+      console.log(chalk.green(`    ${t.icon}  ${t.name}`) + chalk.dim(`  ✓ BuildFlow installed (${scope})`))
+    } else {
+      console.log(chalk.yellow(`    ${t.icon}  ${t.name}`) + chalk.yellow('  ⚠ Detected but BuildFlow not installed'))
+      uninstalled.push(t)
+    }
+  }
+
+  if (uninstalled.length > 0) {
+    console.log('')
+    console.log(chalk.yellow('  Some tools are missing BuildFlow commands.'))
+    console.log(chalk.dim('  Run one of:'))
+    for (const t of uninstalled) {
+      console.log(chalk.white(`    buildflow install --tool ${t.id}`))
+    }
+    console.log(chalk.dim('  Or: buildflow install  (interactive)'))
+  }
+
   if (opts.verbose) {
     console.log(chalk.dim('\n  .buildflow/ structure:'))
     const walk = (dir, prefix = '    ') => {

package/src/commands/update.js

@@ -4,6 +4,7 @@ import { existsSync, readFileSync } from 'fs'
 import { join, dirname } from 'path'
 import { fileURLToPath } from 'url'
 import { run as runInstall } from './install.js'
+import { checkVersion, clearUpdateNotice } from '../utils/checkVersion.js'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 
@@ -15,12 +16,20 @@ export async function run(opts = {}) {
     return
   }
 
+  const pkg = JSON.parse(readFileSync(join(__dirname, '../../package.json'), 'utf8'))
+
   if (opts.check) {
     console.log('\n' + chalk.bold.white('  BuildFlow Update Check\n'))
-    const pkgPath = join(__dirname, '../../package.json')
-    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
-    console.log(chalk.dim(`  Local version: ${pkg.version}`))
-    console.log(chalk.dim('  Run: npx buildflow-dev update  to update commands\n'))
+    const sp = ora('Checking npm registry...').start()
+    const update = await checkVersion(pkg.version)
+    sp.stop()
+
+    if (update) {
+      console.log(chalk.yellow(`  Update available: ${update.current} → ${update.latest}`))
+      console.log(chalk.white('  Run: npx buildflow-dev update\n'))
+    } else {
+      console.log(chalk.green(`  ✓ Up to date (v${pkg.version})\n`))
+    }
     return
   }
 
@@ -30,6 +39,9 @@ export async function run(opts = {}) {
   await new Promise(r => setTimeout(r, 400))
   sp.succeed(chalk.green('  ✓ Command files updated'))
 
+  // Clear the update notice now that we've updated
+  clearUpdateNotice()
+
   console.log('')
   await runInstall({ yes: opts.yes })
 }

package/src/index.js

@@ -1,5 +1,6 @@
 export { run as init }    from './commands/init.js'
 export { run as install } from './commands/install.js'
 export { run as audit }   from './commands/audit.js'
+export { run as fix }     from './commands/fix.js'
 export { run as status }  from './commands/status.js'
 export { run as update }  from './commands/update.js'

package/src/utils/checkVersion.js

@@ -0,0 +1,72 @@
+import { existsSync, writeFileSync, unlinkSync, mkdirSync } from 'fs'
+import { join } from 'path'
+
+const REGISTRY_URL = 'https://registry.npmjs.org/buildflow-dev/latest'
+const UPDATE_FILE  = '.buildflow/core/UPDATE.md'
+
+export async function checkVersion(currentVersion) {
+  try {
+    const res = await fetch(REGISTRY_URL, {
+      signal: AbortSignal.timeout(3000),
+      headers: { Accept: 'application/json' },
+    })
+    if (!res.ok) return null
+
+    const { version: latest } = await res.json()
+    const updatePath = join(process.cwd(), UPDATE_FILE)
+
+    if (latest === currentVersion) {
+      // Remove stale notice if we're already up to date
+      if (existsSync(updatePath)) unlinkSync(updatePath)
+      return null
+    }
+
+    // Only write the file if .buildflow/ exists (i.e. project is initialized)
+    const coreDir = join(process.cwd(), '.buildflow', 'core')
+    if (!existsSync(coreDir)) return { current: currentVersion, latest }
+
+    mkdirSync(coreDir, { recursive: true })
+    writeFileSync(updatePath, buildUpdateNotice(currentVersion, latest))
+
+    return { current: currentVersion, latest }
+  } catch {
+    return null  // Network timeout or offline — silently skip
+  }
+}
+
+export function clearUpdateNotice() {
+  const updatePath = join(process.cwd(), UPDATE_FILE)
+  if (existsSync(updatePath)) unlinkSync(updatePath)
+}
+
+function buildUpdateNotice(current, latest) {
+  return `# BuildFlow Update Available
+
+> A new version of BuildFlow is available.
+> Your AI tool detected this file at session start.
+
+| | Version |
+|---|---|
+| **Installed** | ${current} |
+| **Latest** | ${latest} |
+
+## How to Update
+
+Run this in your terminal:
+
+\`\`\`bash
+npx buildflow-dev update
+\`\`\`
+
+Or if installed globally:
+
+\`\`\`bash
+npm install -g buildflow-dev@latest
+\`\`\`
+
+After updating, this notice will disappear automatically.
+
+---
+*Generated by BuildFlow CLI · ${new Date().toISOString().split('T')[0]}*
+`
+}

package/src/utils/welcome.js

@@ -1,8 +1,21 @@
 import chalk from 'chalk'
 import { existsSync, readFileSync } from 'fs'
-import { join } from 'path'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+import { checkVersion } from './checkVersion.js'
+import { getToolStatus } from '../commands/install.js'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
 
 export async function showWelcome() {
+  const pkg = JSON.parse(readFileSync(join(__dirname, '../../package.json'), 'utf8'))
+  // Fire-and-forget version check — writes UPDATE.md if behind, doesn't block output
+  checkVersion(pkg.version).then(update => {
+    if (update) {
+      console.log(chalk.yellow(`\n  Update available: ${update.current} → ${update.latest}`))
+      console.log(chalk.dim('  Run: npx buildflow-dev update\n'))
+    }
+  }).catch(() => {})
   const isInitialized = existsSync(join(process.cwd(), '.buildflow'))
 
   console.log('\n' + chalk.bold.white('  BuildFlow v3.0'))
@@ -56,6 +69,16 @@ export async function showWelcome() {
     console.log(chalk.white('    buildflow status  ') + chalk.dim('  Show project status'))
     console.log(chalk.white('    buildflow audit   ') + chalk.dim('  Run security audit from terminal'))
     console.log(chalk.white('    buildflow update  ') + chalk.dim('  Update BuildFlow commands'))
+
+    // Surface any newly installed AI tools that don't have BuildFlow yet
+    const uninstalled = getToolStatus().filter(t => t.detected && !t.installedLocal && !t.installedGlobal)
+    if (uninstalled.length > 0) {
+      console.log('')
+      console.log(chalk.yellow(`  New AI tool(s) detected — BuildFlow not installed yet:`))
+      for (const t of uninstalled) {
+        console.log(chalk.yellow(`    ${t.icon}  ${t.name}`) + chalk.dim(`  → buildflow install --tool ${t.id}`))
+      }
+    }
   } else {
     console.log(chalk.yellow('  Not initialized in this directory.\n'))
     console.log(chalk.bold('  Get started:\n'))

package/templates/CLAUDE.md

@@ -2,6 +2,20 @@
 
 This project uses **BuildFlow v3.0** for adaptive AI-powered development orchestration.
 
+## Session Start Checklist (Run Every Time)
+
+Before doing anything else at the start of every session:
+
+1. **Check for updates** — if `.buildflow/core/UPDATE.md` exists, show the user this notice:
+   > "BuildFlow update available — run `npx buildflow-dev update` in your terminal."
+   Then display the contents of UPDATE.md so the user sees the version details.
+   If the file does not exist, proceed silently.
+
+2. **Load memory** — read `.buildflow/memory/light.md` for project context
+3. **Load state** — read `.buildflow/core/state.md` for current phase and status
+
+---
+
 ## Quick Start
 
 Type `/` in Claude Code to see available commands: