rbin-task-flow 1.19.5 → 1.23.0

package/README.md

@@ -33,6 +33,8 @@
 <a id="português"></a>
 # 🇧🇷 Português
 
+> **v1.23.0** — Menos tokens no Cursor (2 regras always-on, checklist de standards, skills). De **1.22**: `npm install -g rbin-task-flow@1.23` e `rbin-task-flow update`. [CHANGELOG](CHANGELOG.md) · [Publicação](RELEASE-1.23.0.md).
+
 ## O Que É Este Projeto?
 
 RBIN Task Flow é um sistema de gerenciamento de tarefas alimentado por IA que configura automaticamente Claude Code e Cursor IDE em qualquer projeto. Você define tarefas em texto simples e a IA gera subtarefas detalhadas e acionáveis automaticamente.
@@ -70,8 +72,12 @@ rbin-task-flow init
 
 ```bash
 rbin-task-flow init          # Inicializa no projeto atual
-rbin-task-flow update        # Atualiza configurações
+rbin-task-flow init --profile minimal  # Só 2 regras always-on + skills (menos tokens no Cursor)
+rbin-task-flow init --share-ai-config  # Versiona .cursor/skills/ e .cursor/rules/ no git (time)
+rbin-task-flow update        # Atualiza configurações (mantém profile em install-meta.json)
+rbin-task-flow update --profile standard  # Passa a copiar todas as regras .mdc
 rbin-task-flow reset         # Reinstala o Task Flow do zero
+rbin-task-flow reset --graphify  # Reset + graphify extract (CLI Graphify no PATH)
 rbin-task-flow version-check # Verifica atualizações de modelos
 rbin-task-flow info          # Mostra informações
 rbin-task-flow check         # Roda lint/fix e build quando existirem
@@ -81,7 +87,21 @@ rbin-task-flow report <ids>  # Gera relatório (ex: "1" ou "1,2" ou "all")
 
 ### Comandos da IA - Por Que Usar?
 
-Após inicializar, use estes comandos na IA (Cursor/Claude) para gerenciar tarefas automaticamente:
+Após inicializar, use estes comandos na IA (Cursor/Claude/Codex) para gerenciar tarefas automaticamente.
+
+**Otimizar por plataforma:** [.task-flow/AI-PLATFORMS.md](.task-flow/AI-PLATFORMS.md) · [Claude](.task-flow/platforms/claude-code.md) · [Cursor](.task-flow/platforms/cursor.md) · [Codex](.task-flow/platforms/codex.md) · [Graphify](.task-flow/GRAPHIFY.md)
+
+**Graphify (opcional):** `rbin-task-flow init --graphify` configura coexistência e pode rodar `graphify extract` (CLI via `rbin-install-dev`).
+
+**Claude Code / Cursor skills (v1.20+):** `init` copia 14 skills para `.claude/skills/` e `.cursor/skills/` — use `/task-flow-sync`, `/task-flow-run`, etc.
+
+**Codex (v1.21+):** `AGENTS.md` com sync/run embutidos, `.task-flow/CODEX.md` sob demanda, `.codex/config.toml` (64 KiB).
+
+**Cursor (v1.23+):** `task-flow-cursor.mdc` + `rbin-git-policy.mdc` (2 always-on) + skills — ver `.task-flow/CURSOR.md`.
+
+**Perfil minimal:** `init --profile minimal` instala só as 2 regras always-on e as 14 skills; workflows via `@task-flow-*` (sem `task_work`, `coding_standards` glob, etc.). `standard` (padrão) copia todas as regras `.cursor/rules/`.
+
+**Compartilhar com o time:** `init --share-ai-config` não ignora `.cursor/skills/` nem `.cursor/rules/` no `.gitignore` (só `.cursor/settings.json` e overrides locais). Padrão: `.cursor/` inteiro ignorado — menos ruído no repo, config local por dev.
 
 | Comando | Por Que Usar | Feature Principal |
 |---------|--------------|-------------------|
@@ -161,9 +181,10 @@ seu-projeto/
 │   │   ├── cursor_rules.mdc
 │   │   ├── self_improve.mdc
 │   │   ├── code_comments.mdc
-│   │   ├── commit_practices.mdc
-│   │   ├── git_control.mdc
-│   │   └── task_execution.mdc
+│   │   ├── rbin-git-policy.mdc    # always-on (git + commits)
+│   │   ├── git_control.mdc        # legacy pointer
+│   │   ├── commit_practices.mdc   # legacy pointer
+│   │   └── task_execution.mdc   # command index stub
 │   └── settings.json             # Configurações do modelo Cursor
 │
 ├── .claude/
@@ -256,6 +277,8 @@ rbin-task-flow update
 
 # Para reiniciar o Task Flow do zero, incluindo .task-flow/.internal
 rbin-task-flow reset
+# Com grafo de código (requer graphify no PATH):
+rbin-task-flow reset --graphify
 
 # Ou usando método legacy
 ~/.rbin-task-flow/install.sh
@@ -299,6 +322,17 @@ rbin-task-flow/
 └── README.md                     # Este arquivo
 ```
 
+## Desenvolvimento (template / CI)
+
+Regressão de tamanho das regras always-on (meta P0: ≤ ~5 KB):
+
+```bash
+npm run measure:rules
+# ou: node scripts/measure-rule-bytes.js --max-kb 5
+```
+
+Lista cada `.cursor/rules/*.mdc` (bytes, linhas, `alwaysApply`), soma always-on vs demais e sai com código **1** se always-on exceder o limite (`--max-kb` ou `RBIN_MAX_ALWAYS_ON_KB`).
+
 ## Notas Importantes
 
 - ⚠️ Este é um **repositório template** - não use RBIN Task Flow aqui
@@ -384,6 +418,8 @@ Para problemas ou perguntas:
 <a id="english"></a>
 # 🇬🇧 English
 
+> **v1.23.0** — Lower Cursor token use (2 always-on rules, standards checklist, skills). From **1.22**: `npm install -g rbin-task-flow@1.23` then `rbin-task-flow update`. [CHANGELOG](CHANGELOG.md) · [Release guide](RELEASE-1.23.0.md).
+
 ## What Is This Project?
 
 RBIN Task Flow is an AI-powered task management system that automatically configures Claude Code and Cursor IDE in any project. You define tasks in plain text and the AI automatically generates detailed, actionable subtasks.
@@ -421,8 +457,12 @@ rbin-task-flow init
 
 ```bash
 rbin-task-flow init          # Initialize in current project
-rbin-task-flow update        # Update configurations
+rbin-task-flow init --profile minimal  # 2 always-on rules + skills only (lower Cursor token cost)
+rbin-task-flow init --share-ai-config  # Commit .cursor/skills and rules with the team
+rbin-task-flow update        # Update configs (keeps profile from .task-flow/install-meta.json)
+rbin-task-flow update --profile standard  # Install all .cursor/rules/*.mdc
 rbin-task-flow reset         # Reinstall Task Flow from scratch
+rbin-task-flow reset --graphify  # Reset + graphify extract (Graphify CLI on PATH)
 rbin-task-flow version-check # Check for model updates
 rbin-task-flow info          # Show information
 rbin-task-flow check         # Run lint/fix and build when available
@@ -432,7 +472,21 @@ rbin-task-flow report <ids>   # Generate report (e.g., "1" or "1,2" or "all")
 
 ### AI Commands - Why Use Them?
 
-After initializing, use these commands in your AI (Cursor/Claude) to automatically manage tasks:
+After initializing, use these commands in your AI (Cursor/Claude/Codex) to automatically manage tasks.
+
+**Per-platform optimization:** [index](.task-flow/AI-PLATFORMS.md) · [Claude](.task-flow/platforms/claude-code.md) · [Cursor](.task-flow/platforms/cursor.md) · [Codex](.task-flow/platforms/codex.md) · [Graphify](.task-flow/GRAPHIFY.md)
+
+**Graphify (optional):** `rbin-task-flow init --graphify` — cooperative setup + optional `graphify extract` (CLI from `rbin-install-dev`).
+
+**Claude / Cursor skills (v1.20+):** installs 14 skills — use `/task-flow-sync`, `/task-flow-run`, etc.
+
+**Codex (v1.21+):** optimized `AGENTS.md`, `.task-flow/CODEX.md`, `.codex/config.toml`.
+
+**Cursor (v1.23+):** 2 always-on rules + 14 skills — `@task-flow-sync`, `@task-flow-run`.
+
+**Minimal profile:** `init --profile minimal` copies only `task-flow-cursor.mdc` and `rbin-git-policy.mdc` plus skills; use `@task-flow-*` for workflows. `standard` (default) copies all rules under `.cursor/rules/`.
+
+**Share with team:** `init --share-ai-config` leaves `.cursor/skills/` and `.cursor/rules/` out of `.gitignore` (see comment block in `.gitignore` for token vs team trade-off). Default ignores all of `.cursor/`.
 
 | Command | Why Use It | Key Feature |
 |---------|------------|-------------|
@@ -512,9 +566,10 @@ your-project/
 │   │   ├── cursor_rules.mdc
 │   │   ├── self_improve.mdc
 │   │   ├── code_comments.mdc
-│   │   ├── commit_practices.mdc
-│   │   ├── git_control.mdc
-│   │   └── task_execution.mdc
+│   │   ├── rbin-git-policy.mdc    # always-on (git + commits)
+│   │   ├── git_control.mdc        # legacy pointer
+│   │   ├── commit_practices.mdc   # legacy pointer
+│   │   └── task_execution.mdc   # command index stub
 │   └── settings.json             # Cursor model settings
 │
 ├── .claude/
@@ -607,6 +662,8 @@ rbin-task-flow update
 
 # To reset Task Flow from scratch, including .task-flow/.internal
 rbin-task-flow reset
+# With code knowledge graph (requires graphify on PATH):
+rbin-task-flow reset --graphify
 
 # Or using legacy method
 ~/.rbin-task-flow/install.sh
@@ -650,6 +707,17 @@ rbin-task-flow/
 └── README.md                     # This file
 ```
 
+## Development (template / CI)
+
+Always-on rule size regression (P0 target: ≤ ~5 KB):
+
+```bash
+npm run measure:rules
+# or: node scripts/measure-rule-bytes.js --max-kb 5
+```
+
+Prints each `.cursor/rules/*.mdc` (bytes, lines, `alwaysApply`), totals always-on vs other, exits **1** if always-on exceeds the limit (`--max-kb` or `RBIN_MAX_ALWAYS_ON_KB`).
+
 ## Important Notes
 
 - ⚠️ This is a **template repository** - don't use RBIN Task Flow here

package/bin/cli.js

@@ -3,6 +3,7 @@
 const { program } = require('commander');
 const path = require('path');
 const { installInProject } = require('../lib/install');
+const { parseProfileOption } = require('../lib/profiles');
 const { checkVersionUpdates } = require('../lib/version');
 const { estimateTask } = require('../lib/estimate');
 const { generateReport } = require('../lib/report');
@@ -15,32 +16,42 @@ program
   .description('AI-powered task management for Claude and Cursor')
   .version(require('../package.json').version);
 
-program
-  .command('init')
-  .description('Initialize RBIN Task Flow in current directory')
-  .option('-p, --path <path>', 'Target directory (default: current directory)')
-  .action(async (options) => {
-    const targetPath = options.path || process.cwd();
-    await installInProject(targetPath);
-  });
-
-program
-  .command('update')
-  .description('Update RBIN Task Flow in current directory')
-  .option('-p, --path <path>', 'Target directory (default: current directory)')
-  .action(async (options) => {
-    const targetPath = options.path || process.cwd();
-    await installInProject(targetPath, { update: true });
-  });
+function addInstallCommand(name, description, extra = {}) {
+  program
+    .command(name)
+    .description(description)
+    .option('-p, --path <path>', 'Target directory (default: current directory)')
+    .option('-g, --graphify', 'Run graphify extract after install (requires graphify CLI)')
+    .option(
+      '--profile <profile>',
+      'Cursor rules: minimal (2 always-on + skills) or standard (all rules); update without flag keeps .task-flow/install-meta.json'
+    )
+    .option(
+      '--share-ai-config',
+      'Do not gitignore .cursor/skills/ or .cursor/rules/ (team can commit shared AI config; see .gitignore comment)'
+    )
+    .action(async (options) => {
+      const targetPath = options.path || process.cwd();
+      try {
+        const profile =
+          options.profile !== undefined ? parseProfileOption(options.profile) : undefined;
+        const shareAiConfig = options.shareAiConfig ? true : undefined;
+        await installInProject(targetPath, {
+          ...extra,
+          graphify: options.graphify,
+          profile,
+          shareAiConfig,
+        });
+      } catch (error) {
+        console.error(chalk.red('\n' + error.message + '\n'));
+        process.exit(1);
+      }
+    });
+}
 
-program
-  .command('reset')
-  .description('Reset RBIN Task Flow in current directory')
-  .option('-p, --path <path>', 'Target directory (default: current directory)')
-  .action(async (options) => {
-    const targetPath = options.path || process.cwd();
-    await installInProject(targetPath, { reset: true });
-  });
+addInstallCommand('init', 'Initialize RBIN Task Flow in current directory');
+addInstallCommand('update', 'Update RBIN Task Flow in current directory', { update: true });
+addInstallCommand('reset', 'Reset RBIN Task Flow in current directory', { reset: true });
 
 program
   .command('version-check')
@@ -99,8 +110,12 @@ program
     console.log(chalk.yellow('Repository:'), 'https://github.com/rbinoliveira/rbin-task-flow');
     console.log(chalk.yellow('\nCommands:'));
     console.log(chalk.cyan('  rbin-task-flow init') + '         - Initialize in current directory');
+    console.log(chalk.cyan('  rbin-task-flow init --profile minimal') + ' - Low-token install (2 always-on rules + skills)');
+    console.log(chalk.cyan('  rbin-task-flow init --share-ai-config') + ' - Version .cursor/skills and rules in git');
+    console.log(chalk.cyan('  rbin-task-flow init --graphify') + ' - Init + graphify extract (if CLI installed)');
     console.log(chalk.cyan('  rbin-task-flow update') + '       - Update configurations');
     console.log(chalk.cyan('  rbin-task-flow reset') + '        - Reset task flow files from scratch');
+    console.log(chalk.cyan('  rbin-task-flow reset --graphify') + ' - Reset + graphify extract (if CLI installed)');
     console.log(chalk.cyan('  rbin-task-flow version-check') + ' - Check for model updates');
     console.log(chalk.cyan('  rbin-task-flow estimate <ids>') + ' - Estimate time (e.g., "1" or "1,2" or "all")');
     console.log(chalk.cyan('  rbin-task-flow report <ids>') + '  - Generate report (e.g., "1" or "1,2" or "all")');

package/lib/codex.js

@@ -0,0 +1,45 @@
+const fs = require('fs-extra');
+const path = require('path');
+const { showSuccess, showInfo, showWarning } = require('./utils');
+
+const TEMPLATE_DIR = path.join(__dirname, '..');
+const CODEX_CONFIG_SRC = path.join(TEMPLATE_DIR, '.codex', 'config.toml');
+
+async function setupCodexIntegration(targetPath, options = {}) {
+  const codexDir = path.join(targetPath, '.codex');
+  const configDest = path.join(codexDir, 'config.toml');
+
+  await fs.ensureDir(codexDir);
+
+  const force = options.forceCodexConfig === true;
+  if (!fs.existsSync(configDest) || force) {
+    if (fs.existsSync(CODEX_CONFIG_SRC)) {
+      await fs.copy(CODEX_CONFIG_SRC, configDest, { overwrite: force });
+      showSuccess('Codex config (.codex/config.toml — project_doc_max_bytes)');
+    }
+  } else {
+    showInfo('Codex config preserved (.codex/config.toml already exists)');
+  }
+
+  const codexWorkflows = path.join(targetPath, '.task-flow', 'CODEX.md');
+  if (fs.existsSync(codexWorkflows)) {
+    showInfo('Codex workflows: .task-flow/CODEX.md (read on demand)');
+  }
+
+  showInfo('Codex entry: AGENTS.md — embedded sync/run + command table');
+  showInfo('Verify: codex --ask-for-approval never "Summarize RBIN Task Flow instructions."');
+
+  const agentsPath = path.join(targetPath, 'AGENTS.md');
+  if (fs.existsSync(agentsPath)) {
+    const size = fs.statSync(agentsPath).size;
+    if (size > 28 * 1024) {
+      showWarning(
+        `AGENTS.md is ${Math.round(size / 1024)} KiB — may truncate with default 32 KiB; .codex/config.toml raises limit`
+      );
+    }
+  }
+
+  return true;
+}
+
+module.exports = { setupCodexIntegration };

package/lib/cursor.js

@@ -0,0 +1,41 @@
+const fs = require('fs-extra');
+const path = require('path');
+const { showSuccess, showInfo } = require('./utils');
+
+async function setupCursorIntegration(targetPath, options = {}) {
+  const profile = options.profile || 'standard';
+  const skillsDir = path.join(targetPath, '.cursor', 'skills');
+  const cursorMd = path.join(targetPath, '.task-flow', 'CURSOR.md');
+  const coreRule = path.join(targetPath, '.cursor', 'rules', 'task-flow-cursor.mdc');
+
+  if (fs.existsSync(coreRule)) {
+    showSuccess('Cursor bootstrap rule (task-flow-cursor.mdc — always on)');
+  }
+
+  if (fs.existsSync(skillsDir)) {
+    const count = (await fs.readdir(skillsDir)).filter((name) =>
+      fs.statSync(path.join(skillsDir, name)).isDirectory()
+    ).length;
+    showInfo(`Cursor skills: ${count} in .cursor/skills/ — use @task-flow-run, @task-flow-sync, …`);
+  }
+
+  if (fs.existsSync(cursorMd)) {
+    showInfo('Cursor guide: .task-flow/CURSOR.md');
+  }
+
+  const gitPolicy = path.join(targetPath, '.cursor', 'rules', 'rbin-git-policy.mdc');
+  if (fs.existsSync(gitPolicy)) {
+    showSuccess('Git policy (rbin-git-policy.mdc — always on)');
+  }
+
+  if (profile === 'minimal') {
+    showInfo('Minimal profile: 2 always-on rules; workflows via @task-flow-* skills only');
+    showInfo('Full rules: rbin-task-flow update --profile standard');
+  } else {
+    showInfo('Rules: 2 always-on + intelligent/glob rules; prefer @task-flow-* skills for workflows');
+  }
+
+  return true;
+}
+
+module.exports = { setupCursorIntegration };

package/lib/gitignore.js

@@ -0,0 +1,101 @@
+const fs = require('fs-extra');
+const path = require('path');
+
+const MARKER_START = '# RBIN Task Flow (rbin-task-flow)';
+const MARKER_END = '# END RBIN Task Flow (rbin-task-flow)';
+
+const ENTRIES_DEFAULT = [
+  '.claude/',
+  '.cursor/',
+  '.task-flow/',
+  'graphify-out/',
+  'CLAUDE.md',
+  'AGENTS.md',
+];
+
+const ENTRIES_SHARE_AI_CONFIG = [
+  '.claude/',
+  '.cursor/settings.json',
+  '.cursor/rules/*.local.mdc',
+  '.task-flow/',
+  'graphify-out/',
+  'CLAUDE.md',
+  'AGENTS.md',
+];
+
+const STRIP_PATTERNS = [
+  ...ENTRIES_DEFAULT,
+  ...ENTRIES_SHARE_AI_CONFIG,
+  MARKER_START,
+  MARKER_END,
+  '# share-ai-config:',
+  '# Trade-off:',
+  '# Default (no flag):',
+];
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function stripRbinGitignoreBlock(content) {
+  let next = content;
+
+  const blockRegex = new RegExp(
+    `\\n?${escapeRegExp(MARKER_START)}[\\s\\S]*?${escapeRegExp(MARKER_END)}\\n?`,
+    'g'
+  );
+  next = next.replace(blockRegex, '\n');
+
+  for (const entry of STRIP_PATTERNS) {
+    const lineRegex = new RegExp(`^${escapeRegExp(entry)}\\s*$`, 'gm');
+    next = next.replace(lineRegex, '');
+  }
+
+  return next.replace(/\n{3,}/g, '\n\n');
+}
+
+function buildRbinGitignoreBlock(shareAiConfig) {
+  const lines = ['', MARKER_START, ''];
+
+  if (shareAiConfig) {
+    lines.push(
+      '# share-ai-config: .cursor/skills/ and .cursor/rules/ are NOT ignored — commit them for team consistency.',
+      '# Trade-off: shared AI config improves workflow parity; each developer still pays token cost when the Agent loads rules/skills.',
+      '# Default (no flag): entire .cursor/ stays local and gitignored — lower repo noise, no team sync of rules.',
+      ''
+    );
+    lines.push(...ENTRIES_SHARE_AI_CONFIG);
+  } else {
+    lines.push(...ENTRIES_DEFAULT);
+  }
+
+  lines.push(MARKER_END, '');
+  return lines.join('\n');
+}
+
+async function updateGitignore(targetPath, { shareAiConfig = false } = {}) {
+  const gitignorePath = path.join(targetPath, '.gitignore');
+
+  if (!fs.existsSync(gitignorePath)) {
+    await fs.writeFile(gitignorePath, '');
+  }
+
+  let content = await fs.readFile(gitignorePath, 'utf8');
+  content = stripRbinGitignoreBlock(content);
+
+  if (!content.endsWith('\n')) {
+    content += '\n';
+  }
+
+  content += buildRbinGitignoreBlock(shareAiConfig);
+  await fs.writeFile(gitignorePath, content);
+
+  return { shareAiConfig };
+}
+
+module.exports = {
+  MARKER_START,
+  buildRbinGitignoreBlock,
+  stripRbinGitignoreBlock,
+  updateGitignore,
+};

package/lib/graphify.js

@@ -0,0 +1,118 @@
+const fs = require('fs-extra');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { showSuccess, showWarning, showInfo } = require('./utils');
+
+const GRAPHIFY_OUT = 'graphify-out/';
+const UPSTREAM_GRAPHIFY_RULE = 'graphify.mdc';
+
+function graphifyCliAvailable() {
+  const result = spawnSync('graphify', ['--help'], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  return result.status === 0 || result.status === 1;
+}
+
+function demoteUpstreamGraphifyRule(targetPath) {
+  const rulePath = path.join(targetPath, '.cursor', 'rules', UPSTREAM_GRAPHIFY_RULE);
+  if (!fs.existsSync(rulePath)) {
+    return false;
+  }
+
+  let content = fs.readFileSync(rulePath, 'utf8');
+  const hadAlwaysApply = /alwaysApply:\s*true/i.test(content);
+
+  if (!hadAlwaysApply) {
+    return false;
+  }
+
+  content = content.replace(/alwaysApply:\s*true/gi, 'alwaysApply: false');
+
+  if (!content.includes('RBIN Task Flow')) {
+    const notice = [
+      '',
+      '- **RBIN Task Flow:** This file was set to `alwaysApply: false` by `rbin-task-flow` to avoid competing with Task Flow rules. Use [.cursor/rules/graphify-task-flow.mdc](mdc:.cursor/rules/graphify-task-flow.mdc) and [.task-flow/GRAPHIFY.md](mdc:.task-flow/GRAPHIFY.md) instead.',
+      '',
+    ].join('\n');
+    content = content.trimEnd() + notice;
+  }
+
+  fs.writeFileSync(rulePath, content);
+  return true;
+}
+
+function ensureGraphifyGitignore(targetPath) {
+  const gitignorePath = path.join(targetPath, '.gitignore');
+  if (!fs.existsSync(gitignorePath)) {
+    return false;
+  }
+
+  let content = fs.readFileSync(gitignorePath, 'utf8');
+  const entry = GRAPHIFY_OUT.replace(/\/$/, '');
+  const linePattern = new RegExp(`^${entry}\\/?$`, 'm');
+
+  if (linePattern.test(content)) {
+    return false;
+  }
+
+  if (!content.endsWith('\n')) {
+    content += '\n';
+  }
+  content += `\n${entry}/\n`;
+  fs.writeFileSync(gitignorePath, content);
+  return true;
+}
+
+function runGraphifyExtract(targetPath) {
+  if (!graphifyCliAvailable()) {
+    showWarning('Graphify CLI not found — skip extract (install via rbin-install-dev Graphify module)');
+    return false;
+  }
+
+  showInfo('Running graphify extract (may take a few minutes)...');
+  const result = spawnSync('graphify', ['extract', '.'], {
+    cwd: targetPath,
+    encoding: 'utf8',
+    stdio: 'inherit',
+  });
+
+  if (result.status !== 0) {
+    showWarning('graphify extract failed — you can run it later: graphify extract .');
+    return false;
+  }
+
+  showSuccess('Graphify knowledge graph (graphify-out/)');
+  return true;
+}
+
+async function setupGraphifyIntegration(targetPath, options = {}) {
+  const demoted = demoteUpstreamGraphifyRule(targetPath);
+  if (demoted) {
+    showSuccess('Graphify upstream rule demoted (alwaysApply: false) — Task Flow keeps priority');
+  }
+
+  const gitignoreUpdated = ensureGraphifyGitignore(targetPath);
+  if (gitignoreUpdated) {
+    showSuccess('graphify-out/ added to .gitignore');
+  }
+
+  if (options.extract) {
+    runGraphifyExtract(targetPath);
+  } else if (graphifyCliAvailable()) {
+    const graphJson = path.join(targetPath, 'graphify-out', 'graph.json');
+    if (!fs.existsSync(graphJson)) {
+      showInfo('Graphify CLI detected — run: graphify extract .  (or: rbin-task-flow init --graphify)');
+    }
+  }
+
+  showInfo('Graphify + Task Flow guide: .task-flow/GRAPHIFY.md');
+}
+
+module.exports = {
+  setupGraphifyIntegration,
+  demoteUpstreamGraphifyRule,
+  ensureGraphifyGitignore,
+  runGraphifyExtract,
+  graphifyCliAvailable,
+};