rbin-task-flow 1.19.2 → 1.19.4

package/.cursor/rules/task_estimate.mdc

@@ -1,5 +1,5 @@
 ---
-description: Task time estimation based on task complexity and developer experience level
+description: Task time estimation based on real task complexity for an average developer pace
 globs: **/*
 alwaysApply: true
 ---
@@ -10,52 +10,45 @@ 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
-    - **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)
+    - **CALCULATE**: Time estimate based on task level, intrinsic complexity signals, and average development pace
+    - **DISPLAY**: Show a single estimate range for the majority of developers
+    - **FORMAT**: Show estimates in hours with ranges (e.g. "10-14 hours")
 
 - **Estimation Rules:**
-  1. **Base Calculation**: Count total number of subtasks in the task
-  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
+  1. **Base Analysis**: Evaluate the task title, description, and subtasks to infer the real complexity of the task itself
+  2. **Assumption**: Estimate for an average developer working at an average development pace, without AI acceleration
+  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. **Intrinsic complexity matters first**: scope, ambiguity, dependencies, validation, integration points, and regression risk must outweigh raw subtask count
+  5. **Subtask count is only one signal**: use it to inform scope, but never as the sole estimate driver
+  6. **Baseline per subtask for average pace**:
+     - Low-level task: 1.5-2.5 hours
+     - Medium-level task: 2.5-4 hours
+     - High-level task: 4-6.5 hours
+  7. **Risk and scope adjustment**:
+     - Increase estimate when the task mentions integrations, migrations, refactors, security, performance, billing, or architecture work
+  8. **Range Calculation**:
+     - Lower bound: subtasks × baseline lower × risk factor
+     - Upper bound: subtasks × baseline upper × risk factor
      - 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 average-pace baseline per subtask from task level
+  3. Apply risk/scope multiplier when complexity indicators exist
+  4. Return one range that represents the majority of developers
   ```
 
 - **Display Format:**
   ```
   📊 Time Estimation for Task X: [Task Title]
   
-  Based on [N] subtasks:
-  
-  👶 Junior (0-2 years):      [X-Y] hours
-  👨‍💼 Intermediate (3-5 years): [X-Y] hours
-  👴 Senior (6+ years):       [X-Y] hours
+  Based on [N] subtasks and task-level analysis:
+
+  Average developer, average pace, no AI acceleration: [X-Y] hours
   ```
 
 - **Natural Language Phrases:**
@@ -72,15 +65,13 @@ 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
-  👴 Senior (6+ years):      7-11 hours
+  Average developer, average pace, no AI acceleration: 10-15 hours
   ```
 
 - **Integration:**
@@ -89,4 +80,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 for an average developer, based on the real complexity of the task itself. Subtask count informs scope, but must not be the sole estimation criterion, and estimates must not assume AI acceleration.**

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,10 +95,10 @@ 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 the real complexity of the task, assuming an average developer working at an average pace without AI acceleration. 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
+- A single estimate range for the majority of developers
 - Estimates in hours and business days
 - Recommendation for management with buffer
 
@@ -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/bin/cli.js

@@ -42,7 +42,7 @@ program
 
 program
   .command('estimate')
-  .description('Estimate time for task(s) based on subtasks and experience level')
+  .description('Estimate time for task(s) based on real task complexity and average development pace')
   .argument('<taskIds>', 'Task ID(s) to estimate (comma-separated or "all")')
   .option('-p, --path <path>', 'Target directory (default: current directory)')
   .action(async (taskIds, options) => {

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,35 +52,25 @@ 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.magenta.bold('Time Estimate for Average Development Pace:\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);
+      console.log(chalk.gray(`Signals: ${analysis.signals.join(', ')}\n`));
 
-      console.log(chalk.gray('👶 Junior Developer (0-2 years):'));
-      console.log(chalk.white('   Hours:'), chalk.yellow(`${estimates.junior.lower}-${estimates.junior.upper} hours`));
-      console.log(chalk.white('   Days: '), chalk.yellow(`~${juniorDays} business day(s)`));
-      console.log('');
-
-      console.log(chalk.gray('👨‍💼 Intermediate (3-5 years):'));
-      console.log(chalk.white('   Hours:'), chalk.yellow(`${estimates.mid.lower}-${estimates.mid.upper} hours`));
-      console.log(chalk.white('   Days: '), chalk.yellow(`~${midDays} business day(s)`));
-      console.log('');
+      const estimateDays = Math.ceil(estimates.upper / 8);
 
-      console.log(chalk.gray('👴 Senior Developer (6+ years):'));
-      console.log(chalk.white('   Hours:'), chalk.yellow(`${estimates.senior.lower}-${estimates.senior.upper} hours`));
-      console.log(chalk.white('   Days: '), chalk.yellow(`~${seniorDays} business day(s)`));
+      console.log(chalk.gray('Assumption: average developer, average delivery pace, without AI acceleration.'));
+      console.log(chalk.white('   Hours:'), chalk.yellow(`${estimates.lower}-${estimates.upper} hours`));
+      console.log(chalk.white('   Days: '), chalk.yellow(`~${estimateDays} business day(s)`));
       console.log('');
 
       console.log(chalk.cyan('─'.repeat(70)));
       console.log(chalk.magenta.bold('Recommendation for Management:\n'));
-      console.log(chalk.white('   Recommended estimate:'), chalk.yellow(`${estimates.mid.lower}-${estimates.mid.upper} hours`), chalk.gray('(3-5 years baseline)'));
+      console.log(chalk.white('   Recommended estimate:'), chalk.yellow(`${estimates.lower}-${estimates.upper} hours`), chalk.gray('(average developer baseline)'));
       console.log(chalk.white('   Buffer recommended:'), chalk.yellow(`+20%`), chalk.gray('for unexpected issues'));
-      console.log(chalk.white('   Total estimate:'), chalk.yellow(`${Math.round(estimates.mid.upper * 1.2)} hours`), chalk.gray(`(~${Math.ceil(estimates.mid.upper * 1.2 / 8)} business days)`));
+      console.log(chalk.white('   Total estimate:'), chalk.yellow(`${Math.round(estimates.upper * 1.2)} hours`), chalk.gray(`(~${Math.ceil(estimates.upper * 1.2 / 8)} business days)`));
       console.log('');
 
       successCount++;
@@ -94,24 +85,108 @@ 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 {
+    lower: Math.round(baseLower),
+    upper: Math.round(baseUpper)
+  };
+}
+
+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 {
-    junior: {
-      lower: Math.round(baseLower * 1.5),
-      upper: Math.round(baseUpper * 1.5)
-    },
-    mid: {
-      lower: baseLower,
-      upper: baseUpper
-    },
-    senior: {
-      lower: Math.round(baseLower * 0.7),
-      upper: Math.round(baseUpper * 0.7)
+    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.4",
   "description": "AI-powered task management for Claude and Cursor",
   "main": "index.js",
   "bin": {