@mthanhlm/autodev 0.4.0 → 0.4.2

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "autodev",
   "description": "A lean Claude Code workflow system with a single entrypoint, task-based phase execution, and read-only git.",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "author": {
     "name": "mthanhlm"
   },

package/README.md

@@ -11,6 +11,7 @@
 - Resolves `.autodev/` state from the repo root even when Claude is started in a nested subdirectory
 - Maps brownfield repos with foreground delegated agents when the environment supports them
 - Runs a multi-lens review pass, using foreground review agents when the environment supports them
+- Can auto-format edited code after Claude writes files when a local formatter is available
 - Ships manual commands when you want direct control:
   - `/autodev-help`
   - `/autodev-new-project`
@@ -111,10 +112,12 @@ project -> track -> phase -> tasks
 - Each task is preferably executed by a fresh foreground delegated agent
 - After each task, the delegated agent reports back with files changed, verification, and blockers
 - `/autodev` stops after each completed task and reopens a task review checkpoint before any further execution
+- If review or verification finds blockers, the same phase stays open and autodev should append remediation task(s) to that phase instead of replacing it or creating a follow-up phase by default
 - No waves by default
 - No automatic parallel execution
 - If specialized agents are unavailable in the current Claude Code environment, the workflow falls back cleanly to current-session execution instead of stopping on platform wording
 - If you want Claude Code itself to hard-disable background task functionality, install with `--disable-background-tasks`, which writes `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1` into Claude Code `settings.json`
+- The post-edit formatter hook uses only locally available tools such as `prettier`, `ruff`, `black`, `gofmt`, `rustfmt`, or `shfmt`, and skips `.autodev/` files
 
 ## Git Policy
 

package/autodev/bin/autodev-tools.cjs

@@ -16,6 +16,7 @@ const DEFAULT_CONFIG = {
     mode: 'read-only'
   },
   hooks: {
+    auto_format: true,
     context_warnings: true,
     read_guard: true,
     workflow_guard: true,
@@ -396,6 +397,10 @@ function lastCompletedTask(tasks) {
   return completed.length > 0 ? completed[completed.length - 1] : null;
 }
 
+function lastTaskNumber(tasks) {
+  return tasks.reduce((highest, task) => Math.max(highest, task.number), 0);
+}
+
 function hasDependencyDeadlock(tasks) {
   return tasks.some(task => !task.summaryExists) && !nextExecutableTask(tasks);
 }
@@ -901,6 +906,7 @@ function initPayload(cwd, mode, requestedPhase) {
   const tasks = phase ? listTasksForPhaseDetails(phase) : [];
   const nextTask = nextExecutableTask(tasks);
   const lastCompleted = lastCompletedTask(tasks);
+  const highestTaskNumber = lastTaskNumber(tasks);
   const dependencyDeadlock = hasDependencyDeadlock(tasks);
   const trackStateSnapshot = track ? readStateSnapshot(track.state) : null;
   const currentTaskNumber = (() => {
@@ -960,6 +966,7 @@ function initPayload(cwd, mode, requestedPhase) {
     task_done_count: tasks.filter(task => task.summaryExists).length,
     all_tasks_done: tasks.length > 0 && tasks.every(task => task.summaryExists),
     dependency_deadlock: dependencyDeadlock,
+    last_task_number: highestTaskNumber,
     next_task_number: nextTask ? nextTask.number : null,
     next_task_path: nextTask ? nextTask.taskPath : null,
     next_task_summary_path: nextTask ? nextTask.summaryPath : null,
@@ -1084,6 +1091,7 @@ module.exports = {
   trackPaths,
   listTasksForPhaseDetails,
   lastCompletedTask,
+  lastTaskNumber,
   hasDependencyDeadlock,
   nextExecutableTask
 };

package/autodev/templates/config.json

@@ -10,6 +10,7 @@
     "mode": "read-only"
   },
   "hooks": {
+    "auto_format": true,
     "context_warnings": true,
     "read_guard": true,
     "workflow_guard": true,

package/autodev/templates/plan.md

@@ -18,6 +18,7 @@ Type: [feature|bugfix|refactor|research|polish]
 - Keep one orchestration session for the phase.
 - Execute one task at a time.
 - No waves by default.
+- If review or verification finds blockers, keep the same phase open and append remediation tasks instead of creating a replacement phase.
 
 ## Phase-Level Risks
 - [Risk]
@@ -32,6 +33,11 @@ Type: [feature|bugfix|refactor|research|polish]
 | 01 | pending | none | [Concrete task goal] |
 | 02 | pending | 01 | [Concrete task goal] |
 
+## Revision Rules
+- Preserve completed task rows and summaries as history.
+- Append remediation tasks after the highest existing task number.
+- Only rewrite pending tasks when needed for clarity.
+
 ## Notes
 - [Anything the delegated agents must know]
 

package/autodev/templates/review.md

@@ -22,3 +22,6 @@ Status: pending
 
 ## Recommendation
 - [Return to execution or continue to verification]
+
+## Remediation Direction
+- [If blocked, append fix task(s) to the same phase and preserve completed task history]

package/autodev/workflows/help.md

@@ -2,6 +2,7 @@
 
 Lean Claude Code workflow. No automatic commits. No branches. No worktrees. Git is read-only.
 It resolves `.autodev/` state from the repo root even when you start Claude in a nested subdirectory.
+It can auto-format edited code after writes when the repo already has a local formatter available.
 
 ## Main Entry
 
@@ -46,6 +47,13 @@ project -> track -> phase -> tasks
 - `task`
   Reviewable execution units inside a phase.
 
+## Blocker Recovery
+
+- Review or verification blockers should normally stay in the same phase.
+- Preserve completed task history.
+- Append `TASK-XX` remediation work to the same phase.
+- Only create a new phase when the blocker reveals genuinely new scope.
+
 ## Default Flow
 
 ```text

package/autodev/workflows/new-project.md

@@ -32,6 +32,7 @@ node "$AUTODEV_ROOT/autodev/bin/autodev-tools.cjs" init new-project
    - `workflow.research: false`
    - `workflow.review_after_execute: true`
    - `git.mode: "read-only"`
+   - `hooks.auto_format: true`
 
 6. Write `.autodev/PROJECT.md` with:
    - one-line summary

package/autodev/workflows/plan-phase.md

@@ -9,6 +9,7 @@ Create one practical phase plan for the active track, then break it into reviewa
 - Optional research is allowed only when the user asks for it or `workflow.research` is true.
 - Never include git write commands in the plan.
 - Do not use waves by default.
+- When revising a blocked phase, preserve the same phase, the same phase goal, and all completed task history.
 </rules>
 
 <process>
@@ -32,6 +33,10 @@ node "$AUTODEV_ROOT/autodev/bin/autodev-tools.cjs" init plan-phase "$ARGUMENTS"
    - `.autodev/tracks/<active-track>/ROADMAP.md`
    - `.autodev/tracks/<active-track>/STATE.md`
    - the target phase section
+   - any existing `TASK-*.md`
+   - any existing `TASK-*-SUMMARY.md`
+   - `NN-REVIEW.md` if it exists
+   - `NN-UAT.md` if it exists
    - any existing code relevant to this phase
 
 5. If research is enabled or explicitly requested, do targeted read-only research only. Keep the output folded into the plan instead of producing a separate research artifact.
@@ -42,14 +47,28 @@ node "$AUTODEV_ROOT/autodev/bin/autodev-tools.cjs" init plan-phase "$ARGUMENTS"
 .autodev/tracks/<active-track>/phases/NN-type-name/
 ```
 
-7. Write or replace `NN-PLAN.md` from the template. The plan must include:
+7. Write or update `NN-PLAN.md` from the template. The plan must include:
    - phase type
    - goal
    - shared verification commands
    - task list overview
    - explicit git read-only reminder
 
-8. Create task files in the same phase directory:
+8. If this phase is being reopened because of `blocked_review`, `blocked_verification`, `blocked_dependencies`, or another blocker status:
+   - keep the same phase directory and phase goal
+   - do not create a new phase for ordinary blockers
+   - do not delete or rewrite completed task summaries
+   - do not renumber completed tasks
+   - preserve already-completed task rows in the phase plan
+   - append new remediation tasks after `last_task_number`
+   - default to one appended remediation task when the blockers are tightly related
+   - split into multiple appended remediation tasks only when the blockers are clearly separate
+   - only rewrite still-pending tasks when that improves clarity
+   - make the new task titles explicit, for example:
+     - `TASK-03: Fix review blockers from 01-REVIEW.md`
+     - `TASK-04: Fix verification gaps from 01-UAT.md`
+
+9. Create or update task files in the same phase directory:
 
 ```text
 TASK-01.md
@@ -75,26 +94,33 @@ Each task file must include:
    - verification
    - done looks like
 
-9. Update the active track `STATE.md` so it points to:
+10. When revising a blocked phase:
+   - point `Current Task` to the first still-pending executable task after the revision
+   - if all existing tasks are completed and you add remediation work, `Current Task` should be the first newly appended fix task
+   - never reset `Current Task` back to `01` just because the phase was replanned
+
+11. Update the active track `STATE.md` so it points to:
    - `Current Phase: N`
    - `Current Phase Type: <type>`
    - `Current Step: plan_review`
-   - `Current Task: 01` if tasks exist, otherwise `none`
+   - `Current Task: <first-pending-task>` if tasks exist, otherwise `none`
    - `Current Task Status: pending_review`
    - `Next Command: /autodev`
    - current ISO timestamp
 
-10. Update `.autodev/STATE.md` so it points to:
+12. Update `.autodev/STATE.md` so it points to:
    - `Active Track: <slug>`
    - `Current Step: plan_review`
-   - `Current Task: 01` if tasks exist, otherwise `none`
+   - `Current Task: <first-pending-task>` if tasks exist, otherwise `none`
    - `Current Task Status: pending_review`
    - `Next Command: /autodev`
    - current ISO timestamp
 
-11. End with a short summary and stop for review.
+13. End with a short summary and stop for review.
    Tell the user:
    - the plan and task files are ready for review
+   - completed task history from the phase was preserved
+   - any blocker remediation was added as appended task work inside the same phase
    - `/autodev` will open the review checkpoint before any execution starts
    - `/autodev-execute-phase N` is only the optional manual bypass after review
 </process>

package/autodev/workflows/review-phase.md

@@ -58,7 +58,9 @@ node "$AUTODEV_ROOT/autodev/bin/autodev-tools.cjs" init review-phase "$ARGUMENTS
    - set `Current Task: none`
    - set `Current Task Status: blocked_review`
    - keep `Next Command: /autodev`
-   - make the recommendation point back to revising the same phase with blocker-fix tasks
+   - make the recommendation point back to revising the same phase with appended blocker-fix tasks
+   - do not recommend creating a new phase for ordinary review blockers
+   - preserve completed task history and phase goal
 
 9. If blockers are not found:
    - set project and track state to `Current Step: verification`

package/autodev/workflows/verify-work.md

@@ -6,6 +6,7 @@ Run lightweight user acceptance testing after review and keep the next action ob
 - Verify against what the phase plan, summary, and review claim.
 - Keep the interaction concise and test-oriented.
 - Do not auto-generate a new plan unless a real gap appears.
+- Verification failures should normally reopen the same phase with appended remediation tasks, not create a new phase.
 </rules>
 
 <process>
@@ -38,6 +39,7 @@ node "$AUTODEV_ROOT/autodev/bin/autodev-tools.cjs" init verify-work "$ARGUMENTS"
    - exact failed behaviors
    - reproduction notes
    - the smallest acceptable fix target
+   - a note that the follow-up should be appended to the same phase as remediation task work unless scope truly changed
 
 7. Update the active track `STATE.md`:
    - if verification passed and another phase remains, move to the next phase and set `Current Step: planning`
@@ -47,6 +49,7 @@ node "$AUTODEV_ROOT/autodev/bin/autodev-tools.cjs" init verify-work "$ARGUMENTS"
    - when verification failed, set `Current Task: none` and `Current Task Status: blocked_verification`
    - always set `Next Command: /autodev`
    - always refresh the ISO timestamp
+   - when verification failed, the next planning pass should preserve completed tasks and append remediation tasks to the same phase
 
 8. Update `.autodev/STATE.md` with the matching project-level status and refreshed timestamp.
 

package/bin/install.js

@@ -14,6 +14,7 @@ const MANAGED_PREFIX = 'autodev-';
 const ROOT_COMMAND = 'autodev';
 const HOOK_FILES = [
   'hooks.json',
+  'autodev-auto-format.js',
   'autodev-paths.js',
   'autodev-context-monitor.js',
   'autodev-git-guard.js',
@@ -375,6 +376,9 @@ function configureSettings(targetDir, isGlobal, options = {}) {
   const contextMonitorCommand = isGlobal
     ? buildGlobalCommand(targetDir, 'autodev-context-monitor.js')
     : buildLocalCommand('autodev-context-monitor.js');
+  const autoFormatCommand = isGlobal
+    ? buildGlobalCommand(targetDir, 'autodev-auto-format.js')
+    : buildLocalCommand('autodev-auto-format.js');
   const promptGuardCommand = isGlobal
     ? buildGlobalCommand(targetDir, 'autodev-prompt-guard.js')
     : buildLocalCommand('autodev-prompt-guard.js');
@@ -402,6 +406,7 @@ function configureSettings(targetDir, isGlobal, options = {}) {
   ensureHook(settings, preToolEvent, 'Write|Edit', readGuardCommand, 5);
   ensureHook(settings, preToolEvent, 'Write|Edit', workflowGuardCommand, 5);
   ensureHook(settings, preToolEvent, 'Bash', gitGuardCommand, 5);
+  ensureHook(settings, postToolEvent, 'Edit|Write|MultiEdit', autoFormatCommand, 10);
   ensureHook(settings, postToolEvent, 'Bash|Edit|Write|MultiEdit|Agent|Task', contextMonitorCommand, 10);
   ensureHook(settings, postToolEvent, 'Write|Edit', phaseBoundaryCommand, 5);
 

package/hooks/autodev-auto-format.js

@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { findWorkspaceRoot, readProjectConfig } = require('./autodev-paths.js');
+
+const PRETTIER_EXTENSIONS = new Set([
+  '.js', '.jsx', '.cjs', '.mjs',
+  '.ts', '.tsx',
+  '.json',
+  '.css', '.scss', '.less',
+  '.html',
+  '.yml', '.yaml',
+  '.vue', '.svelte'
+]);
+
+const PYTHON_EXTENSIONS = new Set(['.py']);
+const SHELL_EXTENSIONS = new Set(['.sh', '.bash', '.zsh']);
+
+function fileExists(filePath) {
+  try {
+    return fs.existsSync(filePath);
+  } catch {
+    return false;
+  }
+}
+
+function isFile(filePath) {
+  try {
+    return fs.statSync(filePath).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function isInside(targetPath, rootPath) {
+  const relative = path.relative(rootPath, targetPath);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+function resolveHookFilePath(data, cwd) {
+  const raw = data.tool_input?.file_path || data.tool_input?.path || '';
+  if (!raw) {
+    return null;
+  }
+  return path.isAbsolute(raw) ? raw : path.resolve(cwd, raw);
+}
+
+function resolveExecutable(workspaceRoot, candidates) {
+  for (const candidate of candidates) {
+    if (Array.isArray(candidate)) {
+      const absolute = path.join(workspaceRoot, ...candidate);
+      if (isFile(absolute)) {
+        return absolute;
+      }
+
+      if (process.platform === 'win32' && isFile(`${absolute}.cmd`)) {
+        return `${absolute}.cmd`;
+      }
+
+      if (process.platform === 'win32' && isFile(`${absolute}.exe`)) {
+        return `${absolute}.exe`;
+      }
+
+      if (isFile(`${absolute}.cmd`)) {
+        return `${absolute}.cmd`;
+      }
+
+      if (isFile(`${absolute}.exe`)) {
+        return `${absolute}.exe`;
+      }
+
+      if (isFile(`${absolute}.js`)) {
+        return `${absolute}.js`;
+      }
+
+      if (fileExists(absolute)) {
+        return absolute;
+      }
+      continue;
+    }
+
+    const result = spawnSync('sh', ['-lc', `command -v "${candidate}"`], {
+      cwd: workspaceRoot,
+      encoding: 'utf8'
+    });
+    if (result.status === 0 && result.stdout.trim()) {
+      return result.stdout.trim();
+    }
+  }
+
+  return null;
+}
+
+function resolveFile(workspaceRoot, candidates) {
+  for (const candidate of candidates) {
+    const absolute = path.join(workspaceRoot, ...candidate);
+    if (isFile(absolute)) {
+      return absolute;
+    }
+  }
+
+  return null;
+}
+
+function formatterCommand(filePath, workspaceRoot) {
+  const ext = path.extname(filePath).toLowerCase();
+
+  if (PRETTIER_EXTENSIONS.has(ext)) {
+    const prettierScript = resolveFile(workspaceRoot, [
+      ['node_modules', 'prettier', 'bin', 'prettier.cjs'],
+      ['node_modules', 'prettier', 'bin', 'prettier.js']
+    ]);
+    if (prettierScript) {
+      return [process.execPath, [prettierScript, '--write', filePath]];
+    }
+
+    const prettier = resolveExecutable(workspaceRoot, [
+      ['node_modules', '.bin', 'prettier'],
+      'prettier'
+    ]);
+    return prettier ? [prettier, ['--write', filePath]] : null;
+  }
+
+  if (PYTHON_EXTENSIONS.has(ext)) {
+    const ruff = resolveExecutable(workspaceRoot, [
+      ['.venv', 'bin', 'ruff'],
+      ['.venv', 'Scripts', 'ruff.exe'],
+      'ruff'
+    ]);
+    if (ruff) {
+      return [ruff, ['format', filePath]];
+    }
+
+    const black = resolveExecutable(workspaceRoot, [
+      ['.venv', 'bin', 'black'],
+      ['.venv', 'Scripts', 'black.exe'],
+      'black'
+    ]);
+    return black ? [black, [filePath]] : null;
+  }
+
+  if (ext === '.go') {
+    const gofmt = resolveExecutable(workspaceRoot, ['gofmt']);
+    return gofmt ? [gofmt, ['-w', filePath]] : null;
+  }
+
+  if (ext === '.rs') {
+    const rustfmt = resolveExecutable(workspaceRoot, ['rustfmt']);
+    return rustfmt ? [rustfmt, [filePath]] : null;
+  }
+
+  if (SHELL_EXTENSIONS.has(ext)) {
+    const shfmt = resolveExecutable(workspaceRoot, ['shfmt']);
+    return shfmt ? [shfmt, ['-w', filePath]] : null;
+  }
+
+  return null;
+}
+
+try {
+  const input = fs.readFileSync(0, 'utf8');
+  const data = JSON.parse(input);
+  if (!['Edit', 'Write', 'MultiEdit'].includes(data.tool_name)) {
+    process.exit(0);
+  }
+
+  const cwd = data.cwd || process.cwd();
+  const workspaceRoot = findWorkspaceRoot(cwd);
+  const config = readProjectConfig(cwd);
+  if (config && config.hooks?.auto_format === false) {
+    process.exit(0);
+  }
+
+  const filePath = resolveHookFilePath(data, cwd);
+  if (!filePath || !isFile(filePath)) {
+    process.exit(0);
+  }
+
+  const autodevRoot = path.join(workspaceRoot, '.autodev');
+  if (fileExists(autodevRoot) && isInside(filePath, autodevRoot)) {
+    process.exit(0);
+  }
+
+  const formatter = formatterCommand(filePath, workspaceRoot);
+  if (!formatter) {
+    process.exit(0);
+  }
+
+  const [command, args] = formatter;
+  const result = spawnSync(command, args, {
+    cwd: workspaceRoot,
+    encoding: 'utf8'
+  });
+
+  if (result.status !== 0) {
+    const stderr = (result.stderr || '').trim();
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PostToolUse',
+        additionalContext: stderr
+          ? `AUTO-FORMAT WARNING: formatting failed for ${path.basename(filePath)}: ${stderr}`
+          : `AUTO-FORMAT WARNING: formatting failed for ${path.basename(filePath)}.`
+      }
+    }));
+  }
+} catch {
+  process.exit(0);
+}

package/hooks/hooks.json

@@ -54,6 +54,16 @@
       }
     ],
     "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/autodev-auto-format.js\"",
+            "timeout": 10
+          }
+        ]
+      },
       {
         "matcher": "Bash|Edit|Write|MultiEdit|Agent|Task",
         "hooks": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mthanhlm/autodev",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "A lean Claude Code workflow system with a single entrypoint, task-based phase execution, and read-only git.",
   "bin": {
     "autodev": "bin/install.js"