rbin-task-flow 1.19.2 → 1.19.3

package/.cursor/rules/task_estimate.mdc

@@ -10,48 +10,48 @@ alwaysApply: true
   - **ALL TASKS**: `task-flow: estimate all` → Estimate all tasks
   - When user says "task-flow: estimate X", "estimate X", "estimate X,Y", "estimate all", or "how long will task X take":
     - **READ**: `.task-flow/.internal/tasks.json` to get task details
-    - **CALCULATE**: Time estimate based on number of subtasks and developer experience level
+    - **CALCULATE**: Time estimate based on task level, complexity signals, and developer experience level
     - **DISPLAY**: Show time estimate with intervals for 3 experience levels (junior, mid, senior)
     - **FORMAT**: Show estimates in hours with ranges (e.g., "10-14 hours" for intermediate)
 
 - **Estimation Rules:**
-  1. **Base Calculation**: Count total number of subtasks in the task
+  1. **Base Analysis**: Evaluate the task title and subtasks to infer real task level
   2. **Experience Levels** (use internally; display "Intermediate" not "Mid-level" to user):
      - **Junior** (0-2 years): Base time × 1.5 multiplier
      - **Intermediate** (3-5 years): Base time × 1.0 multiplier (baseline)
      - **Senior** (6+ years): Base time × 0.7 multiplier
-  3. **Time per Subtask**:
-     - Simple subtask: 1-2 hours (intermediate baseline)
-     - Medium subtask: 2-4 hours (intermediate baseline)
-     - Complex subtask: 4-6 hours (intermediate baseline)
-  4. **Default Assumption**: Average 2-3 hours per subtask for intermediate (baseline)
-  5. **Range Calculation**: 
-     - Lower bound: (subtasks × 2) × multiplier
-     - Upper bound: (subtasks × 3) × multiplier
+  3. **Task Level Heuristics**:
+     - **Low**: localized change, clear requirement, low ambiguity, low regression risk
+     - **Medium**: multi-file implementation, moderate ambiguity, moderate validation needs
+     - **High**: architectural, cross-cutting, migration, security, performance, or high-risk change
+  4. **Subtask count is only one signal**: use it to inform scope, but never as the sole estimate driver
+  5. **Intermediate baseline per subtask**:
+     - Low-level task: 1.5-2.5 hours
+     - Medium-level task: 2.5-4 hours
+     - High-level task: 4-6.5 hours
+  6. **Risk and scope adjustment**:
+     - Increase estimate when the task mentions integrations, migrations, refactors, security, performance, billing, or architecture work
+  7. **Range Calculation**:
+     - Lower bound: (subtasks × baseline lower) × risk factor × experience multiplier
+     - Upper bound: (subtasks × baseline upper) × risk factor × experience multiplier
      - Round to nearest hour
 
 - **Estimation Formula:**
   ```
-  Base hours per subtask: 2-3 hours (intermediate)
-  
-  Junior (0-2 years):
-    Lower: (subtasks × 2) × 1.5
-    Upper: (subtasks × 3) × 1.5
-  
-  Intermediate (3-5 years):
-    Lower: subtasks × 2
-    Upper: subtasks × 3
-  
-  Senior (6+ years):
-    Lower: (subtasks × 2) × 0.7
-    Upper: (subtasks × 3) × 0.7
+  1. Infer task level: low, medium, or high
+  2. Choose intermediate baseline per subtask from task level
+  3. Apply risk/scope multiplier when complexity indicators exist
+  4. Apply experience multiplier:
+     Junior: × 1.5
+     Intermediate: × 1.0
+     Senior: × 0.7
   ```
 
 - **Display Format:**
   ```
   📊 Time Estimation for Task X: [Task Title]
   
-  Based on [N] subtasks:
+  Based on [N] subtasks and task-level analysis:
   
   👶 Junior (0-2 years):      [X-Y] hours
   👨‍💼 Intermediate (3-5 years): [X-Y] hours
@@ -72,11 +72,11 @@ alwaysApply: true
   ```
   User: "task-flow: estimate 1"
   
-  Task 1 has 5 subtasks:
+  Task 1 has 5 subtasks and medium complexity signals:
   
   📊 Time Estimation for Task 1: Create authentication system
   
-  Based on 5 subtasks:
+  Based on 5 subtasks and task-level analysis:
   
   👶 Junior (0-2 years):      15-23 hours
   👨‍💼 Intermediate (3-5 years): 10-15 hours
@@ -89,4 +89,4 @@ alwaysApply: true
   - Estimates are informational only (not stored)
 
 - **Principle:**
-  > **Provide realistic time estimates based on task complexity (number of subtasks) and developer experience level. Show ranges to account for variability in implementation speed.**
+  > **Provide realistic time estimates based on real task level, scope, ambiguity, and risk. Subtask count informs scope, but must not be the sole estimation criterion.**

package/.cursor/rules/task_generate_flow.mdc

@@ -8,19 +8,30 @@ alwaysApply: true
   - **FAST FORMAT**: `task-flow: generate flow` → Populate tasks.flow.md
   - When user says "task-flow: generate flow", "generate flow", "gerar flow", or "flow":
     - **READ**: `.task-flow/.internal/tasks.json` and optionally `status.json`
-    - **SEARCH**: Current versions of Codex, Composer, Claude (Haiku, Sonnet) via web search
+    - **SEARCH**: Current versions of GPT-5.x, Composer, Claude (Haiku, Sonnet) via web search
     - **WRITE**: Populate `.task-flow/tasks.flow.md` with the generated flow
   - **DO NOT**: Populate tasks.flow.md when running `task-flow: sync`
 
 - **Generation Process:**
-  1. **Search for current model versions** (web search): Codex, Composer (Cursor), Claude Haiku, Claude Sonnet. Include version next to each model (e.g. "Claude Sonnet 4.6").
+  1. **Search for current model versions** (web search): one GPT-5.x coding-capable model, Composer (Cursor), Claude Haiku, Claude Sonnet. Include version next to each model (e.g. "Claude Sonnet 4.6").
   2. Read tasks from tasks.json
   3. For each task, determine:
      - **Dependencies**: Which tasks must be completed first (or "—" if none)
-     - **Estimated hours** (for billing): subtasks × 2 to subtasks × 3 hours. Do NOT show "dev mediano" or "mid-level".
-     - **3 model options** (in order of priority): one Codex, one Composer, one Claude — always these 3. Include version and effort for each.
-     - **Effort** per model: low (1-3 subtasks), medium (4-6), high (7+ or complex)
+     - **Estimated hours** (for billing): infer from real task scope, ambiguity, dependencies, and validation needs. Subtask count informs scope, but do not use a fixed subtasks × hours formula. Do NOT show "dev mediano" or "mid-level".
+     - **3 model options** (in order of priority): one GPT-5.x model, one Composer, one Claude — always these 3. Include version and effort for each.
+     - **Model priority must be defined by AI judgment**, based on task nature, implementation risk, ambiguity, architecture impact, validation needs, and expected autonomy. Do not use a fixed ranking.
+     - **Effort** per model: low, medium, or high, defined by task level and difficulty. Do not infer effort from subtask count alone.
   4. **Claude**: Use only Haiku or Sonnet — **never Opus**
+  5. **Effort heuristics**:
+     - **low**: localized change, clear requirement, low ambiguity, low regression risk, limited validation
+     - **medium**: multi-file implementation, moderate ambiguity, moderate regression risk, requires broader validation
+     - **high**: architecture or cross-cutting change, high ambiguity, high regression risk, sequencing concerns, or deep investigation/refactor
+  6. **Model heuristics**:
+     - **GPT-5.x**: prioritize when the task needs strong implementation, refactoring, debugging, or broader code reasoning
+     - **Composer**: prioritize when the task benefits from editor-native iteration, repo-wide navigation, and fast execution in the coding flow
+     - **Claude Haiku**: prioritize for simpler, well-bounded tasks with low effort
+     - **Claude Sonnet**: prioritize for tasks that need more synthesis, reasoning depth, or architectural analysis
+     - The first recommendation must reflect the best fit for that specific task, not a template order reused across all tasks
 
 - **Output Format (direct blocks per task):**
   ```markdown
@@ -37,7 +48,7 @@ alwaysApply: true
   | ⚡ | Pode iniciar agora (deps satisfeitas) |
   | 🔒 | Bloqueada por dependências |
 
-  **Esforço (Effort):** low (1-3 subtasks), medium (4-6), high (7+)
+  **Esforço (Effort):** definido pelo nível e dificuldade real da task, não pela quantidade de subtasks
   **Claude:** Haiku ou Sonnet — **não use Opus**
 
   ## Tasks (blocos diretos por task)
@@ -46,7 +57,7 @@ alwaysApply: true
   - **Depende de:** —
   - **Horas cobrança:** 10-15h
   - **Modelos sugeridos** (ordem de prioridade):
-    1. Codex [versão] — effort medium
+    1. GPT-5.x [versão] — effort medium
     2. Composer [versão] — effort medium
     3. Claude Sonnet [versão] — effort medium
 
@@ -54,8 +65,8 @@ alwaysApply: true
   - **Depende de:** Task 1 ✅
   - **Horas cobrança:** 10-15h
   - **Modelos sugeridos** (ordem de prioridade):
-    1. Codex [versão] — effort medium
-    2. Composer [versão] — effort medium
+    1. Composer [versão] — effort medium
+    2. GPT-5.x [versão] — effort medium
     3. Claude Sonnet [versão] — effort medium
 
   ### 🔒 Task 3 — [Título]
@@ -63,17 +74,18 @@ alwaysApply: true
   - **Horas cobrança:** 8-12h
   - **Modelos sugeridos** (ordem de prioridade):
     1. Claude Haiku [versão] — effort low
-    2. Codex [versão] — effort low
+    2. GPT-5.x [versão] — effort low
     3. Composer [versão] — effort low
   ```
 
 - **Model Rules:**
-  - **3 models per task**: One Codex, one Composer, one Claude — always in order of priority
+  - **3 models per task**: One GPT-5.x model, one Composer, one Claude — always in order of priority
   - **Version required**: Include current version next to each model name (from web search)
   - **Effort required**: low, medium, or high for each model
+  - **AI-defined ranking**: order models by best fit for the task, not by a fixed global priority
   - **No Opus**: Claude = Haiku or Sonnet only
 
 - **Natural Language:** "generate flow", "gerar flow", "flow"
 
 - **Principle:**
-  > **Populate tasks.flow.md with direct blocks per task. Dependencies, hours, and 3 model options (Codex, Composer, Claude) with version and effort. Never use Opus.**
+  > **Populate tasks.flow.md with direct blocks per task. Dependencies, hours, and 3 model options (GPT-5.x, Composer, Claude) with version and effort. Let AI define ranking and effort from task context. Never use Opus.**

package/.task-flow/README.md

@@ -95,7 +95,7 @@ Refactors code from specific task(s). Removes explanatory comments, improves cod
 - `task-flow: refactor all` → Refactors all tasks
 
 ### `task-flow: estimate X` (simplified syntax)
-Estimates time required to complete task(s) based on the number of subtasks and developer experience level.
+Estimates time required to complete task(s) based on task level, scope, risk, and developer experience level. Subtask count informs scope, but is not the sole criterion.
 
 **Output includes:**
 - Time estimates for Junior (0-2 years), Intermediate (3-5 years), and Senior (6+ years) developers
@@ -108,7 +108,7 @@ Estimates time required to complete task(s) based on the number of subtasks and
 - `task-flow: estimate all` → Shows time estimates for all tasks
 
 ### `task-flow: generate flow`
-Populates `tasks.flow.md` with: (1) task dependencies (for parallelization), (2) estimated hours, and (3) AI model recommendations (Codex, Composer, Claude) with effort levels. Run after `task-flow: sync` when you want to know which tasks can run in parallel and which model/effort to use.
+Populates `tasks.flow.md` with: (1) task dependencies (for parallelization), (2) estimated hours, and (3) AI model recommendations (GPT-5.x, Composer, Claude) with effort levels. Model ranking and effort must be defined by the AI from task context, not from a fixed order or only from subtask count. Run after `task-flow: sync` when you want to know which tasks can run in parallel and which model/effort to use.
 
 ### `task-flow: report X` (simplified syntax)
 Generates a detailed implementation report for completed task(s) in Markdown format.

package/lib/estimate.js

@@ -40,7 +40,8 @@ async function estimateTask(taskIdsInput, targetPath = process.cwd()) {
         continue;
       }
 
-      const estimates = calculateEstimates(subtaskCount);
+      const analysis = analyzeTaskComplexity(task);
+      const estimates = calculateEstimates(analysis);
 
       if (taskIds.length > 1) {
         console.log('\n' + chalk.cyan('═'.repeat(70)));
@@ -51,11 +52,13 @@ async function estimateTask(taskIdsInput, targetPath = process.cwd()) {
       console.log(chalk.cyan('═'.repeat(70)) + '\n');
 
       console.log(chalk.blue.bold('Task:'), chalk.yellow(`#${taskId} - ${task.title}\n`));
-      console.log(chalk.blue(`Complexity: ${chalk.yellow(subtaskCount)} subtasks\n`));
+      console.log(chalk.blue(`Complexity: ${chalk.yellow(analysis.level)} (${subtaskCount} subtasks)\n`));
 
       console.log(chalk.cyan('─'.repeat(70)));
       console.log(chalk.magenta.bold('Time Estimates by Experience Level:\n'));
 
+      console.log(chalk.gray(`Signals: ${analysis.signals.join(', ')}\n`));
+
       const juniorDays = Math.ceil(estimates.junior.upper / 8);
       const midDays = Math.ceil(estimates.mid.upper / 8);
       const seniorDays = Math.ceil(estimates.senior.upper / 8);
@@ -94,9 +97,16 @@ async function estimateTask(taskIdsInput, targetPath = process.cwd()) {
   }
 }
 
-function calculateEstimates(subtaskCount) {
-  const baseLower = subtaskCount * 2;
-  const baseUpper = subtaskCount * 3;
+function calculateEstimates(analysis) {
+  const { subtaskCount, level, riskMultiplier } = analysis;
+  const levelRanges = {
+    low: { lower: 1.5, upper: 2.5 },
+    medium: { lower: 2.5, upper: 4 },
+    high: { lower: 4, upper: 6.5 }
+  };
+  const baseRange = levelRanges[level] || levelRanges.medium;
+  const baseLower = subtaskCount * baseRange.lower * riskMultiplier;
+  const baseUpper = subtaskCount * baseRange.upper * riskMultiplier;
 
   return {
     junior: {
@@ -114,4 +124,91 @@ function calculateEstimates(subtaskCount) {
   };
 }
 
+function analyzeTaskComplexity(task) {
+  const subtasks = Array.isArray(task.subtasks) ? task.subtasks : [];
+  const subtaskCount = subtasks.length;
+  const content = buildTaskContent(task, subtasks);
+  const keywordScores = scoreKeywords(content);
+
+  let score = 0;
+
+  if (subtaskCount <= 2) score += 1;
+  else if (subtaskCount <= 5) score += 2;
+  else score += 3;
+
+  score += keywordScores.complexity;
+
+  let level = 'medium';
+  if (score <= 2) level = 'low';
+  else if (score >= 6) level = 'high';
+
+  const riskMultiplier = Math.max(1, 1 + keywordScores.risk * 0.08 + keywordScores.scope * 0.06);
+  const signals = [
+    `${subtaskCount} subtasks`,
+    `${level} task level`
+  ];
+
+  if (keywordScores.scope > 0) signals.push('multi-file or integration indicators');
+  if (keywordScores.risk > 0) signals.push('risk or validation indicators');
+  if (keywordScores.architecture > 0) signals.push('architecture/refactor indicators');
+  if (signals.length === 2) signals.push('no elevated complexity indicators');
+
+  return {
+    subtaskCount,
+    level,
+    riskMultiplier,
+    signals
+  };
+}
+
+function buildTaskContent(task, subtasks) {
+  const parts = [task.title, task.description];
+
+  for (const subtask of subtasks) {
+    if (typeof subtask === 'string') {
+      parts.push(subtask);
+      continue;
+    }
+
+    if (subtask && typeof subtask === 'object') {
+      parts.push(subtask.title, subtask.description);
+    }
+  }
+
+  return parts
+    .filter(Boolean)
+    .join(' ')
+    .toLowerCase();
+}
+
+function scoreKeywords(content) {
+  const architectureKeywords = [
+    'architecture', 'arquitetura', 'refactor', 'refator', 'migrate', 'migra',
+    'core', 'infra', 'foundation', 'sdk', 'abstraction'
+  ];
+  const scopeKeywords = [
+    'integration', 'integracao', 'integrar', 'api', 'database', 'banco',
+    'auth', 'oauth', 'deploy', 'pipeline', 'webhook', 'service', 'provider'
+  ];
+  const riskKeywords = [
+    'critical', 'critico', 'security', 'seguranca', 'performance', 'perf',
+    'bug', 'fix', 'regression', 'migration', 'compliance', 'billing', 'payment'
+  ];
+
+  const architecture = countMatches(content, architectureKeywords);
+  const scope = countMatches(content, scopeKeywords);
+  const risk = countMatches(content, riskKeywords);
+
+  return {
+    architecture,
+    scope,
+    risk,
+    complexity: architecture * 2 + scope + risk
+  };
+}
+
+function countMatches(content, keywords) {
+  return keywords.reduce((total, keyword) => total + (content.includes(keyword) ? 1 : 0), 0);
+}
+
 module.exports = { estimateTask };

package/lib/install.js

@@ -120,10 +120,10 @@ async function copyConfigs(targetPath, isUpdate = false) {
     showSuccess('Codex instructions (AGENTS.md)');
   }
 
-  await copyTaskFlow(targetPath);
+  await copyTaskFlow(targetPath, isUpdate);
 }
 
-async function copyTaskFlow(targetPath) {
+async function copyTaskFlow(targetPath, isUpdate = false) {
   const taskFlowSrc = path.join(TEMPLATE_DIR, '.task-flow');
   const taskFlowDest = path.join(targetPath, '.task-flow');
 
@@ -132,11 +132,24 @@ async function copyTaskFlow(targetPath) {
   const PROTECTED = [
     path.join(taskFlowDest, '.internal'),
   ];
+  const PRESERVED_ON_INIT = [
+    path.join(taskFlowDest, 'tasks.input.txt'),
+    path.join(taskFlowDest, 'tasks.status.md'),
+    path.join(taskFlowDest, 'tasks.flow.md'),
+  ];
 
   await fs.copy(taskFlowSrc, taskFlowDest, {
     overwrite: true,
-    filter: (src) => {
-      return !PROTECTED.some((p) => src.startsWith(p));
+    filter: (src, dest) => {
+      if (PROTECTED.some((p) => src.startsWith(p) || dest.startsWith(p))) {
+        return false;
+      }
+
+      if (!isUpdate && PRESERVED_ON_INIT.includes(dest) && fs.existsSync(dest)) {
+        return false;
+      }
+
+      return true;
     },
   });
 
@@ -154,8 +167,12 @@ async function copyTaskFlow(targetPath) {
     await fs.writeFile(flowPath, flowStub);
   }
 
-  showSuccess('Task Flow directory (overwritten)');
-  showInfo('Protected: .internal/ (your task data is safe)');
+  showSuccess('Task Flow directory');
+  if (isUpdate) {
+    showInfo('Protected: .internal/ (your task data is safe)');
+  } else {
+    showInfo('Protected on init: .internal/, tasks.input.txt, tasks.status.md, tasks.flow.md');
+  }
 }
 
 async function updateGitignore(targetPath) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rbin-task-flow",
-  "version": "1.19.2",
+  "version": "1.19.3",
   "description": "AI-powered task management for Claude and Cursor",
   "main": "index.js",
   "bin": {