@mthanhlm/autodev 0.3.6 → 0.4.0

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.3.6",
+  "version": "0.4.0",
   "author": {
     "name": "mthanhlm"
   },

package/PUBLISH.md

@@ -40,7 +40,7 @@ npm publish --access public
 
 ## Later Releases
 
-1. Bump the version in `package.json`.
+1. Bump the version in both `package.json` and `.claude-plugin/plugin.json`.
 2. Regenerate the tarball:
 
 ```bash

package/README.md

@@ -8,14 +8,16 @@
 - Keeps project state in `.autodev/`
 - Uses `/autodev` as the main command
 - Organizes work as `project -> track -> phase -> tasks`
-- Maps brownfield repos with parallel codebase agents when the environment supports them
-- Runs a multi-lens review pass, using parallel review agents when the environment supports them
+- 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
 - Ships manual commands when you want direct control:
   - `/autodev-help`
   - `/autodev-new-project`
   - `/autodev-explore-codebase`
   - `/autodev-plan-phase`
   - `/autodev-execute-phase`
+  - `/autodev-review-task`
   - `/autodev-review-phase`
   - `/autodev-verify-work`
   - `/autodev-cleanup`
@@ -43,6 +45,12 @@ Local install for one repo:
 npx @mthanhlm/autodev@latest --local
 ```
 
+Install and also disable Claude Code background tasks in the target `settings.json`:
+
+```bash
+npx @mthanhlm/autodev@latest --global --disable-background-tasks
+```
+
 Uninstall:
 
 ```bash
@@ -64,8 +72,10 @@ Typical brownfield route:
   -> explore codebase
   -> plan phase
   -> review phase plan
-  -> execute next task
-  -> execute next task
+  -> execute one task
+  -> review task
+  -> execute one task
+  -> review task
   -> review
   -> verify
 ```
@@ -99,10 +109,12 @@ project -> track -> phase -> tasks
 - `/autodev` stops after planning so the user can review the phase before any execution starts
 - The phase keeps one user-facing orchestration session
 - Each task is preferably executed by a fresh foreground delegated agent
-- After each task, the worker reports back with files changed, verification, and blockers
+- 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
 - No waves by default
-- No parallel execution unless the user explicitly asks for it later
+- 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`
 
 ## Git Policy
 

package/autodev/bin/autodev-tools.cjs

@@ -9,12 +9,9 @@ const DEFAULT_CONFIG = {
   },
   workflow: {
     research: false,
-    review_after_execute: true,
-    codebase_parallel_agents: 4
-  },
-  execution: {
-    parallel: false
+    review_after_execute: true
   },
+  execution: {},
   git: {
     mode: 'read-only'
   },
@@ -31,13 +28,38 @@ const DEFAULT_CONFIG = {
 
 const CODEBASE_FILES = ['structure.md', 'domain.md', 'runtime.md', 'quality.md', 'summary.md'];
 
+function findWorkspaceRoot(startDir) {
+  let cursor = path.resolve(startDir || process.cwd());
+  let gitRoot = null;
+
+  while (true) {
+    if (fileExists(path.join(cursor, '.autodev'))) {
+      return cursor;
+    }
+
+    if (!gitRoot && fileExists(path.join(cursor, '.git'))) {
+      gitRoot = cursor;
+    }
+
+    const parent = path.dirname(cursor);
+    if (parent === cursor) {
+      break;
+    }
+    cursor = parent;
+  }
+
+  return gitRoot || path.resolve(startDir || process.cwd());
+}
+
 function autodevDir(cwd) {
-  return path.join(cwd, '.autodev');
+  return path.join(findWorkspaceRoot(cwd), '.autodev');
 }
 
 function rootPaths(cwd) {
+  const workspaceRoot = findWorkspaceRoot(cwd);
   const root = autodevDir(cwd);
   return {
+    workspaceRoot,
     root,
     config: path.join(root, 'config.json'),
     project: path.join(root, 'PROJECT.md'),
@@ -86,6 +108,7 @@ function padPhase(number) {
 }
 
 function detectExistingCodebase(cwd) {
+  const workspaceRoot = findWorkspaceRoot(cwd);
   const knownFiles = [
     'package.json',
     'package-lock.json',
@@ -117,16 +140,16 @@ function detectExistingCodebase(cwd) {
     '__tests__'
   ];
 
-  if (knownFiles.some(name => fileExists(path.join(cwd, name)))) {
+  if (knownFiles.some(name => fileExists(path.join(workspaceRoot, name)))) {
     return true;
   }
 
-  if (knownDirs.some(name => fileExists(path.join(cwd, name)))) {
+  if (knownDirs.some(name => fileExists(path.join(workspaceRoot, name)))) {
     return true;
   }
 
   try {
-    const entries = fs.readdirSync(cwd, { withFileTypes: true });
+    const entries = fs.readdirSync(workspaceRoot, { withFileTypes: true });
     return entries.some(entry => {
       if (entry.name === '.autodev' || entry.name === '.claude' || entry.name.startsWith('.')) {
         return false;
@@ -257,6 +280,35 @@ function readSingleLineField(content, label) {
   return match ? match[1].trim() : null;
 }
 
+function parseStateSnapshot(content) {
+  if (!content) {
+    return null;
+  }
+
+  const currentPhaseRaw = readSingleLineField(content, 'Current Phase');
+  const currentPhaseNumber = currentPhaseRaw && /^\d+$/.test(currentPhaseRaw)
+    ? Number(currentPhaseRaw)
+    : null;
+
+  return {
+    currentPhase: currentPhaseNumber,
+    currentPhaseType: readSingleLineField(content, 'Current Phase Type'),
+    currentStep: readSingleLineField(content, 'Current Step'),
+    currentTask: readSingleLineField(content, 'Current Task'),
+    currentTaskStatus: readSingleLineField(content, 'Current Task Status'),
+    status: readSingleLineField(content, 'Status'),
+    nextCommand: readSingleLineField(content, 'Next Command')
+  };
+}
+
+function readStateSnapshot(filePath) {
+  return parseStateSnapshot(readText(filePath));
+}
+
+function isBlockedTaskStatus(value) {
+  return typeof value === 'string' && /^blocked/i.test(value.trim());
+}
+
 function parseTaskDependsOn(value) {
   if (!value || /^none$/i.test(value)) {
     return [];
@@ -336,9 +388,16 @@ function listTasksForPhaseDetails(phaseDetails) {
 }
 
 function nextExecutableTask(tasks) {
-  return tasks.find(task => !task.summaryExists && task.ready)
-    || tasks.find(task => !task.summaryExists)
-    || null;
+  return tasks.find(task => !task.summaryExists && task.ready) || null;
+}
+
+function lastCompletedTask(tasks) {
+  const completed = tasks.filter(task => task.summaryExists);
+  return completed.length > 0 ? completed[completed.length - 1] : null;
+}
+
+function hasDependencyDeadlock(tasks) {
+  return tasks.some(task => !task.summaryExists) && !nextExecutableTask(tasks);
 }
 
 function listPhases(cwd, slug = readActiveTrack(cwd)) {
@@ -396,19 +455,51 @@ function resolvePhase(cwd, slug, requestedPhase, mode) {
     return phases.find(phase => phase.number === numeric) || null;
   }
 
+  const track = trackPaths(cwd, slug);
+  const trackState = track ? readStateSnapshot(track.state) : null;
+  const currentStatePhase = trackState?.currentPhase
+    ? phases.find(phase => phase.number === trackState.currentPhase) || null
+    : null;
+
   if (mode === 'plan') {
+    if (currentStatePhase && (
+      isBlockedTaskStatus(trackState.currentTaskStatus)
+      || trackState.currentStep === 'planning'
+      || trackState.currentStep === 'plan_review'
+    )) {
+      return currentStatePhase;
+    }
     return phases.find(phase => !phase.planExists) || phases[0];
   }
 
   if (mode === 'execute') {
+    if (currentStatePhase && (
+      trackState?.currentStep === 'execution'
+      || trackState?.currentStep === 'task_review'
+    )) {
+      return currentStatePhase;
+    }
     return phases.find(phase => phase.planExists && !phase.summaryExists) || null;
   }
 
+  if (mode === 'task_review') {
+    if (currentStatePhase && trackState?.currentStep === 'task_review') {
+      return currentStatePhase;
+    }
+    return phases.find(phase => phase.planExists && !phase.summaryExists && phase.taskDoneCount > 0) || null;
+  }
+
   if (mode === 'review') {
+    if (currentStatePhase && trackState?.currentStep === 'review') {
+      return currentStatePhase;
+    }
     return phases.find(phase => phase.summaryExists && !phase.reviewExists) || null;
   }
 
   if (mode === 'verify') {
+    if (currentStatePhase && trackState?.currentStep === 'verification') {
+      return currentStatePhase;
+    }
     return phases.find(phase => phase.reviewExists && !phase.uatExists)
       || [...phases].reverse().find(phase => phase.reviewExists)
       || null;
@@ -470,6 +561,7 @@ function buildRoute(cwd) {
   }
 
   const phases = listPhases(cwd, activeTrack);
+  const trackState = readStateSnapshot(track.state);
   if (phases.length === 0) {
     return {
       kind: 'track_setup',
@@ -481,6 +573,84 @@ function buildRoute(cwd) {
     };
   }
 
+  const currentStatePhase = trackState?.currentPhase
+    ? phases.find(phase => phase.number === trackState.currentPhase) || null
+    : null;
+
+  if (currentStatePhase && (
+    isBlockedTaskStatus(trackState?.currentTaskStatus)
+  )) {
+    return {
+      kind: 'plan_phase',
+      command: '/autodev',
+      manualCommand: `/autodev-plan-phase ${currentStatePhase.number}`,
+      reason: 'blocked_phase_requires_replanning',
+      projectType,
+      trackSlug: activeTrack,
+      phaseNumber: currentStatePhase.number
+    };
+  }
+
+  if (currentStatePhase && trackState?.currentStep === 'execution') {
+    return {
+      kind: 'execute_phase',
+      command: '/autodev',
+      manualCommand: `/autodev-execute-phase ${currentStatePhase.number}`,
+      reason: 'phase_execution_in_progress',
+      projectType,
+      trackSlug: activeTrack,
+      phaseNumber: currentStatePhase.number
+    };
+  }
+
+  if (currentStatePhase && trackState?.currentStep === 'task_review') {
+    return {
+      kind: 'task_review',
+      command: '/autodev',
+      manualCommand: `/autodev-review-task ${currentStatePhase.number}`,
+      reason: 'task_execution_checkpoint_pending_user_review',
+      projectType,
+      trackSlug: activeTrack,
+      phaseNumber: currentStatePhase.number
+    };
+  }
+
+  if (currentStatePhase && trackState?.currentStep === 'plan_review') {
+    return {
+      kind: 'plan_review',
+      command: '/autodev',
+      manualCommand: `/autodev-execute-phase ${currentStatePhase.number}`,
+      reason: 'phase_plan_awaits_review',
+      projectType,
+      trackSlug: activeTrack,
+      phaseNumber: currentStatePhase.number
+    };
+  }
+
+  if (currentStatePhase && trackState?.currentStep === 'review' && !currentStatePhase.reviewExists) {
+    return {
+      kind: 'review_phase',
+      command: '/autodev',
+      manualCommand: `/autodev-review-phase ${currentStatePhase.number}`,
+      reason: 'phase_review_in_progress',
+      projectType,
+      trackSlug: activeTrack,
+      phaseNumber: currentStatePhase.number
+    };
+  }
+
+  if (currentStatePhase && trackState?.currentStep === 'verification' && !currentStatePhase.uatExists) {
+    return {
+      kind: 'verify_phase',
+      command: '/autodev',
+      manualCommand: `/autodev-verify-work ${currentStatePhase.number}`,
+      reason: 'phase_verification_in_progress',
+      projectType,
+      trackSlug: activeTrack,
+      phaseNumber: currentStatePhase.number
+    };
+  }
+
   const nextReview = phases.find(phase => phase.summaryExists && !phase.reviewExists);
   if (nextReview && config.workflow.review_after_execute !== false) {
     return {
@@ -507,6 +677,19 @@ function buildRoute(cwd) {
     };
   }
 
+  const nextTaskReview = phases.find(phase => phase.planExists && !phase.summaryExists && phase.taskDoneCount > 0);
+  if (nextTaskReview) {
+    return {
+      kind: 'task_review',
+      command: '/autodev',
+      manualCommand: `/autodev-review-task ${nextTaskReview.number}`,
+      reason: 'phase_task_completed_awaiting_user_review',
+      projectType,
+      trackSlug: activeTrack,
+      phaseNumber: nextTaskReview.number
+    };
+  }
+
   const nextPlannedReview = phases.find(phase => phase.planExists && !phase.summaryExists);
   if (nextPlannedReview) {
     return {
@@ -643,6 +826,7 @@ function buildStatus(cwd) {
 
   return {
     cwd,
+    workspace_root: paths.workspaceRoot,
     autodev_exists: fileExists(paths.root),
     project_exists: fileExists(paths.project),
     existing_code_detected: existingCodebase,
@@ -706,6 +890,8 @@ function initPayload(cwd, mode, requestedPhase) {
     ? 'review'
     : mode === 'verify-work'
       ? 'verify'
+      : mode === 'review-task'
+        ? 'task_review'
       : mode === 'execute-phase' || mode === 'review-plan'
         ? 'execute'
         : mode === 'plan-phase'
@@ -714,6 +900,17 @@ function initPayload(cwd, mode, requestedPhase) {
   const phase = phaseMode && activeTrack ? resolvePhase(cwd, activeTrack, requestedPhase, phaseMode) : null;
   const tasks = phase ? listTasksForPhaseDetails(phase) : [];
   const nextTask = nextExecutableTask(tasks);
+  const lastCompleted = lastCompletedTask(tasks);
+  const dependencyDeadlock = hasDependencyDeadlock(tasks);
+  const trackStateSnapshot = track ? readStateSnapshot(track.state) : null;
+  const currentTaskNumber = (() => {
+    const raw = trackStateSnapshot?.currentTask;
+    if (raw && /^\d+$/.test(raw)) {
+      return Number(raw);
+    }
+    return lastCompleted ? lastCompleted.number : null;
+  })();
+  const currentTask = tasks.find(task => task.number === currentTaskNumber) || lastCompleted || null;
   const codebase = codebasePaths(cwd);
 
   return {
@@ -742,6 +939,7 @@ function initPayload(cwd, mode, requestedPhase) {
     requirements_path: track ? track.requirements : null,
     roadmap_path: track ? track.roadmap : null,
     track_state_path: track ? track.state : null,
+    track_state: trackStateSnapshot,
     phases_dir: track ? track.phasesDir : null,
     route,
     phase_found: Boolean(phase),
@@ -761,9 +959,15 @@ function initPayload(cwd, mode, requestedPhase) {
     task_count: tasks.length,
     task_done_count: tasks.filter(task => task.summaryExists).length,
     all_tasks_done: tasks.length > 0 && tasks.every(task => task.summaryExists),
+    dependency_deadlock: dependencyDeadlock,
     next_task_number: nextTask ? nextTask.number : null,
     next_task_path: nextTask ? nextTask.taskPath : null,
     next_task_summary_path: nextTask ? nextTask.summaryPath : null,
+    current_task_number: currentTask ? currentTask.number : null,
+    current_task_path: currentTask ? currentTask.taskPath : null,
+    current_task_summary_path: currentTask ? currentTask.summaryPath : null,
+    last_completed_task_number: lastCompleted ? lastCompleted.number : null,
+    last_completed_task_summary_path: lastCompleted ? lastCompleted.summaryPath : null,
     tasks: tasks.map(task => ({
       number: task.number,
       title: task.title,
@@ -867,6 +1071,7 @@ module.exports = {
   buildRoute,
   buildStatus,
   detectExistingCodebase,
+  findWorkspaceRoot,
   initPayload,
   listPhases,
   listTracks,
@@ -878,5 +1083,7 @@ module.exports = {
   rootPaths,
   trackPaths,
   listTasksForPhaseDetails,
+  lastCompletedTask,
+  hasDependencyDeadlock,
   nextExecutableTask
 };

package/autodev/templates/config.json

@@ -4,11 +4,7 @@
   },
   "workflow": {
     "research": false,
-    "review_after_execute": true,
-    "codebase_parallel_agents": 4
-  },
-  "execution": {
-    "parallel": false
+    "review_after_execute": true
   },
   "git": {
     "mode": "read-only"

package/autodev/workflows/autodev.md

@@ -27,6 +27,7 @@ node "$AUTODEV_ROOT/autodev/bin/autodev-tools.cjs" status
    - `plan_phase`: load and perform the plan-phase workflow.
    - `plan_review`: load and perform the review-plan workflow so the user can review the phase plan before any execution starts.
    - `execute_phase`: load and perform the execute-phase workflow, which should advance one task-sized unit in the current phase session by trying a fresh foreground agent first and falling back cleanly when agent delegation is unavailable.
+   - `task_review`: load and perform the review-task workflow so the user can review one completed task before any further execution starts.
    - `review_phase`: load and perform the review-phase workflow.
    - `verify_phase`: load and perform the verify-work workflow.
 

package/autodev/workflows/execute-phase.md

@@ -42,7 +42,7 @@ node "$AUTODEV_ROOT/autodev/bin/autodev-tools.cjs" init execute-phase "$ARGUMENT
 5. Determine the next executable task:
    - prefer the first task without a summary whose dependencies are already done
    - if no executable task remains and all task summaries exist, move to phase aggregation
-   - if task dependencies are inconsistent, stop and ask the user how to repair the plan
+   - if `dependency_deadlock` is true, stop before execution, set both state files to `Current Step: planning`, set `Current Task: none`, set `Current Task Status: blocked_dependencies`, keep `Next Command: /autodev`, and ask the user how to repair the plan
 
 6. Before running a task, show the user:
    - task id and title
@@ -68,10 +68,10 @@ node "$AUTODEV_ROOT/autodev/bin/autodev-tools.cjs" init execute-phase "$ARGUMENT
 
 8. If worker delegation is unavailable, do not stop on the raw platform message.
    Treat messages like `specialized agents aren't available` as a capability limitation, then:
-   - tell the user plainly that worker-agent delegation is unavailable in this environment
+   - tell the user plainly that delegated-agent execution is unavailable in this environment
    - continue with the same task in the current session
    - keep the same task boundaries
-   - still write the task summary before moving on
+   - still write the task summary before stopping
 
 9. After the delegated agent returns, or after the current-session fallback completes:
    - confirm `TASK-NN-SUMMARY.md` exists
@@ -80,11 +80,12 @@ node "$AUTODEV_ROOT/autodev/bin/autodev-tools.cjs" init execute-phase "$ARGUMENT
 
 10. If more tasks remain:
    - update project and track state to:
-     - `Current Step: execution`
-     - `Current Task: <next-task>`
-     - `Current Task Status: ready`
+     - `Current Step: task_review`
+     - `Current Task: <current-task>`
+     - `Current Task Status: complete`
      - `Next Command: /autodev`
-   - end by telling the user `/autodev` will continue with the next task
+   - stop after this task
+   - end by telling the user `/autodev` will open the task review checkpoint before any next-task execution
 
 11. If all tasks are done:
    - write or update `NN-SUMMARY.md` from the template with:
@@ -97,26 +98,30 @@ node "$AUTODEV_ROOT/autodev/bin/autodev-tools.cjs" init execute-phase "$ARGUMENT
 12. Update the active track `STATE.md` so it points to:
    - `Current Phase: N`
    - `Current Phase Type: <type>`
-   - `Current Step: review`
-   - `Current Task: none`
+   - `Current Step: task_review`
+   - `Current Task: <current-task>`
    - `Current Task Status: complete`
    - `Next Command: /autodev`
    - current ISO timestamp
 
 13. Update `.autodev/STATE.md` so it points to:
    - `Active Track: <slug>`
-   - `Current Step: review`
-   - `Current Task: none`
+   - `Current Step: task_review`
+   - `Current Task: <current-task>`
    - `Current Task Status: complete`
    - `Next Command: /autodev`
    - current ISO timestamp
 
 14. If the current task is blocked or incomplete:
    - say so clearly in the task summary
-   - set both state files to `Current Step: execution`
+   - set both state files to `Current Step: planning`
    - set `Current Task: <same-task>`
    - set `Current Task Status: blocked`
    - keep `Next Command: /autodev`
+   - tell the user the phase should be revised before more execution
 
-15. End with a short outcome summary and the next recommended command. Mention that the automatic review bundle is the next routed step only when the whole phase is complete.
+15. End with a short outcome summary and the next recommended command.
+   - Never execute a second task in the same run.
+   - If all tasks are now done, say `/autodev` will open the phase-review checkpoint next.
+   - Otherwise, say `/autodev` will open the task-review checkpoint for the completed task.
 </process>

package/autodev/workflows/explore-codebase.md

@@ -3,7 +3,7 @@ Map a brownfield repository quickly and produce a usable codebase brief without
 </purpose>
 
 <rules>
-- Prefer four parallel agents for this workflow when specialized agents are available.
+- Prefer a small set of foreground codebase agents, run one at a time, when agent delegation is available.
 - Give each agent a disjoint write target.
 - Use read-only investigation only. No git writes.
 - Focus on information that will improve planning and execution for the active track.
@@ -26,7 +26,7 @@ node "$AUTODEV_ROOT/autodev/bin/autodev-tools.cjs" init explore-codebase
    - the active track docs if they exist
    - representative repo files needed to orient the exploration
 
-4. If specialized agents are available, explicitly call the `Agent` tool four times with these installed subagents and owned outputs:
+4. If agent delegation is available, explicitly call the `Agent` tool for these subagents, one at a time in the foreground, with owned outputs:
    - `autodev-codebase-structure` for standalone installs, or `autodev:autodev-codebase-structure` in direct plugin runs, owns `.autodev/codebase/structure.md`
    - `autodev-codebase-domain` for standalone installs, or `autodev:autodev-codebase-domain` in direct plugin runs, owns `.autodev/codebase/domain.md`
    - `autodev-codebase-runtime` for standalone installs, or `autodev:autodev-codebase-runtime` in direct plugin runs, owns `.autodev/codebase/runtime.md`

package/autodev/workflows/help.md

@@ -1,6 +1,7 @@
 # autodev
 
 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.
 
 ## Main Entry
 
@@ -14,13 +15,15 @@ Lean Claude Code workflow. No automatic commits. No branches. No worktrees. Git
 - `/autodev-new-project`
   Creates project state in `.autodev/` and the first active track under `.autodev/tracks/<track>/`.
 - `/autodev-explore-codebase`
-  Uses four parallel agents when available to map a brownfield repo into `.autodev/codebase/`.
+  Uses foreground codebase agents, one at a time when available, to map a brownfield repo into `.autodev/codebase/`.
 - `/autodev-plan-phase [phase]`
   Creates or revises one phase plan plus task files in `.autodev/tracks/<track>/phases/NN-type-name/`.
 - `/autodev-execute-phase [phase]`
-  Orchestrates one phase task-by-task, preferring a fresh foreground delegated agent per task, and writes `TASK-NN-SUMMARY.md` plus the final `NN-SUMMARY.md`.
+  Orchestrates exactly one task for the phase, preferring a fresh foreground delegated agent, and writes `TASK-NN-SUMMARY.md`.
+- `/autodev-review-task [phase]`
+  Pauses after one completed task so the user can review the result before executing the next task or starting phase review.
 - `/autodev-review-phase [phase]`
-  Uses four review agents when available for code quality, security, integration, and polish, then writes `NN-REVIEW.md`.
+  Uses foreground review agents, one at a time when available, for code quality, security, integration, and polish, then writes `NN-REVIEW.md`.
 - `/autodev-verify-work [phase]`
   Records manual verification in `NN-UAT.md` and captures fix-return gaps when verification fails.
 - `/autodev-progress`
@@ -58,6 +61,9 @@ Typical brownfield route:
   -> plan
   -> review plan
   -> execute
+  -> review task
+  -> execute
+  -> review task
   -> review
   -> verify
   -> next track or cleanup
@@ -85,9 +91,12 @@ Blocked:
 - `git merge`
 - `git rebase`
 - `git worktree`
+- `git clean`
+- `git cherry-pick`
 - `git push`
 - `git pull`
 - `git stash`
 - `git reset`
 - `git fetch`
 - `git clone`
+- mutating `git branch`, `git tag`, and `git remote` commands

package/autodev/workflows/new-project.md

@@ -31,8 +31,6 @@ node "$AUTODEV_ROOT/autodev/bin/autodev-tools.cjs" init new-project
    - `project.type: "greenfield"` or `"brownfield"`
    - `workflow.research: false`
    - `workflow.review_after_execute: true`
-   - `workflow.codebase_parallel_agents: 4`
-   - `execution.parallel: false`
    - `git.mode: "read-only"`
 
 6. Write `.autodev/PROJECT.md` with:

package/autodev/workflows/review-phase.md

@@ -3,7 +3,7 @@ Run the automatic review bundle after execution so the user sees code quality, s
 </purpose>
 
 <rules>
-- Prefer four review agents in parallel when specialized agents are available.
+- Prefer a small set of foreground review agents, run one at a time, when agent delegation is available.
 - Review findings should be concrete and evidence-based.
 - Do not edit repository code in this step unless the user explicitly asks for fixes.
 - Write one consolidated review artifact for the phase.
@@ -28,7 +28,7 @@ node "$AUTODEV_ROOT/autodev/bin/autodev-tools.cjs" init review-phase "$ARGUMENTS
    - `NN-SUMMARY.md`
    - relevant source files and tests
 
-4. If specialized agents are available, explicitly call the `Agent` tool four times with these installed review subagents:
+4. If agent delegation is available, explicitly call the `Agent` tool for these review subagents, one at a time in the foreground:
    - `autodev-review-quality` for standalone installs, or `autodev:autodev-review-quality` in direct plugin runs
    - `autodev-review-security` for standalone installs, or `autodev:autodev-review-security` in direct plugin runs
    - `autodev-review-integration` for standalone installs, or `autodev:autodev-review-integration` in direct plugin runs
@@ -54,9 +54,11 @@ node "$AUTODEV_ROOT/autodev/bin/autodev-tools.cjs" init review-phase "$ARGUMENTS
    - a final recommendation
 
 8. If blockers are found:
-   - set project and track state back to `Current Step: execution`
+   - set project and track state back to `Current Step: planning`
+   - set `Current Task: none`
+   - set `Current Task Status: blocked_review`
    - keep `Next Command: /autodev`
-   - make the recommendation point back to the same phase
+   - make the recommendation point back to revising the same phase with blocker-fix tasks
 
 9. If blockers are not found:
    - set project and track state to `Current Step: verification`

package/autodev/workflows/review-plan.md

@@ -32,13 +32,14 @@ node "$AUTODEV_ROOT/autodev/bin/autodev-tools.cjs" init review-plan "$ARGUMENTS"
    - shared verification plan
 
 5. Ask the user what to do next with `AskUserQuestion`:
-   - execute the next task now
+   - execute one task now
    - revise the phase plan
    - stop here
 
 6. If the user chooses to execute now:
    - load the execute-phase workflow
-   - perform it in the same turn
+   - perform exactly one task in the same turn
+   - stop after that task completes
 
 7. If the user chooses to revise the plan:
    - load the plan-phase workflow

package/autodev/workflows/review-task.md

@@ -0,0 +1,70 @@
+<purpose>
+Pause after one completed task so the user can review the outcome before more execution happens in the same phase.
+</purpose>
+
+<rules>
+- This is a control checkpoint, not an execution step.
+- Do not auto-run the next task from this checkpoint without explicit user approval.
+- Prefer `/autodev` as the entrypoint even at this checkpoint.
+- If all tasks are done, do not auto-start phase review without explicit user approval.
+</rules>
+
+<process>
+1. Run:
+
+```bash
+AUTODEV_ROOT="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude}"
+node "$AUTODEV_ROOT/autodev/bin/autodev-tools.cjs" init review-task "$ARGUMENTS"
+```
+
+2. If no phase is found, stop and direct the user to `/autodev`.
+
+3. Read:
+   - `.autodev/STATE.md`
+   - the active track `STATE.md`
+   - `NN-PLAN.md`
+   - all `TASK-*.md`
+   - the current task summary from `current_task_summary_path`
+   - if `Current Task` is missing or stale, infer the checkpoint task from the most recent existing `TASK-*-SUMMARY.md`
+   - `NN-SUMMARY.md` if it exists
+
+4. Show the user a concise checkpoint summary:
+   - completed task id and title
+   - what changed
+   - verification run
+   - blockers or open concerns
+   - the next ready task, if any
+
+5. If more tasks remain, ask the user what to do next with `AskUserQuestion`:
+   - execute the next task now
+   - revise the phase plan
+   - stop here
+
+6. If all tasks are done, ask the user what to do next with `AskUserQuestion`:
+   - run phase review now
+   - revise the phase plan
+   - stop here
+
+7. If the user chooses to execute the next task:
+   - load the execute-phase workflow
+   - perform exactly one task in the same turn
+   - stop again after that task completes
+
+8. If the user chooses to run phase review:
+   - load the review-phase workflow
+   - perform it in the same turn
+
+9. If the user chooses to revise the plan:
+   - load the plan-phase workflow
+   - revise the same phase in the same turn
+
+10. If the user chooses to stop here:
+   - keep both state files on:
+     - `Current Step: task_review`
+     - `Current Task: <current-task>`
+     - `Current Task Status: complete`
+     - `Next Command: /autodev`
+   - end with a short note that no further execution has started
+
+11. End with a short outcome summary and `/autodev` as the default next command.
+</process>

package/autodev/workflows/verify-work.md

@@ -42,9 +42,9 @@ node "$AUTODEV_ROOT/autodev/bin/autodev-tools.cjs" init verify-work "$ARGUMENTS"
 7. Update the active track `STATE.md`:
    - if verification passed and another phase remains, move to the next phase and set `Current Step: planning`
    - if verification passed and no phase remains, set `Current Step: complete`
-   - if verification failed, keep the same phase active and set `Current Step: execution`
+   - if verification failed, keep the same phase active and set `Current Step: planning`
    - when moving to another phase, set `Current Task: none` and `Current Task Status: idle`
-   - when verification failed, set `Current Task: none` and `Current Task Status: idle`
+   - when verification failed, set `Current Task: none` and `Current Task Status: blocked_verification`
    - always set `Next Command: /autodev`
    - always refresh the ISO timestamp
 

package/bin/install.js

@@ -14,6 +14,7 @@ const MANAGED_PREFIX = 'autodev-';
 const ROOT_COMMAND = 'autodev';
 const HOOK_FILES = [
   'hooks.json',
+  'autodev-paths.js',
   'autodev-context-monitor.js',
   'autodev-git-guard.js',
   'autodev-phase-boundary.sh',
@@ -268,6 +269,13 @@ function removeManagedSettings(settings) {
     delete settings.statusLine;
   }
 
+  if (settings.env && typeof settings.env === 'object') {
+    delete settings.env.CLAUDE_CODE_DISABLE_BACKGROUND_TASKS;
+    if (Object.keys(settings.env).length === 0) {
+      delete settings.env;
+    }
+  }
+
   if (!settings.hooks || typeof settings.hooks !== 'object') {
     return settings;
   }
@@ -321,6 +329,13 @@ function ensureHook(settings, eventName, matcher, command, timeout) {
   settings.hooks[eventName].push(entry);
 }
 
+function ensureEnvSetting(settings, name, value) {
+  if (!settings.env || typeof settings.env !== 'object') {
+    settings.env = {};
+  }
+  settings.env[name] = String(value);
+}
+
 function setExecutableBits(targetDir) {
   const candidates = [
     path.join(targetDir, 'hooks', 'autodev-phase-boundary.sh'),
@@ -397,6 +412,10 @@ function configureSettings(targetDir, isGlobal, options = {}) {
     };
   }
 
+  if (options.disableBackgroundTasks) {
+    ensureEnvSetting(settings, 'CLAUDE_CODE_DISABLE_BACKGROUND_TASKS', '1');
+  }
+
   writeSettings(settingsPath, settings);
   return settingsPath;
 }
@@ -546,6 +565,8 @@ function printHelp() {
 Options:
   --global      Install to Claude Code config directory
   --local       Install to the current project (.claude/)
+  --disable-background-tasks
+                Set CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 in Claude Code settings.json
   --uninstall   Remove autodev from the selected location
   --help        Show this help
 
@@ -553,6 +574,7 @@ Examples:
   npx @mthanhlm/autodev@latest
   npx @mthanhlm/autodev@latest --global
   npx @mthanhlm/autodev@latest --local
+  npx @mthanhlm/autodev@latest --global --disable-background-tasks
   npx @mthanhlm/autodev@latest --global --uninstall
 `);
 }
@@ -582,6 +604,27 @@ Location:
   });
 }
 
+function askDisableBackgroundTasks() {
+  return new Promise(resolve => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    console.log(`
+Background tasks:
+  ${cyan}1${reset}) Disable in Claude Code settings ${yellow}(Recommended for autodev)${reset}
+      -> sets CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1
+  ${cyan}2${reset}) Leave background-task settings unchanged
+`);
+    rl.question(`Select background-task policy ${yellow}[1]${reset}: `, answer => {
+      rl.close();
+      const trimmed = answer.trim().toLowerCase();
+      if (trimmed === '2' || trimmed === 'n' || trimmed === 'no' || trimmed === 'leave') {
+        resolve(false);
+        return;
+      }
+      resolve(true);
+    });
+  });
+}
+
 async function main() {
   const args = process.argv.slice(2);
   if (args.includes('--help') || args.includes('-h')) {
@@ -590,20 +633,30 @@ async function main() {
   }
 
   let scope = null;
+  let scopeWasExplicit = false;
   if (args.includes('--global') || args.includes('-g')) {
     scope = 'global';
+    scopeWasExplicit = true;
   } else if (args.includes('--local') || args.includes('-l')) {
     scope = 'local';
+    scopeWasExplicit = true;
   }
 
   if (!scope) {
     scope = await askScope();
   }
 
-  if (args.includes('--uninstall') || args.includes('-u')) {
+  const uninstallRequested = args.includes('--uninstall') || args.includes('-u');
+  const disableBackgroundTasks = args.includes('--disable-background-tasks')
+    ? true
+    : uninstallRequested || scopeWasExplicit
+      ? false
+      : await askDisableBackgroundTasks();
+
+  if (uninstallRequested) {
     uninstall({ scope });
   } else {
-    install({ scope });
+    install({ scope, disableBackgroundTasks });
   }
 }
 

package/commands/autodev/execute-phase.md

@@ -1,6 +1,6 @@
 ---
 name: autodev:execute-phase
-description: Execute an active-track phase task by task, preferring fresh foreground agents with clean fallback when unavailable
+description: Execute exactly one active-track task at a time, preferring a fresh foreground agent with clean fallback when unavailable
 argument-hint: "[phase-number]"
 allowed-tools:
   - Read
@@ -14,7 +14,7 @@ allowed-tools:
   - Agent
 ---
 <objective>
-Execute one active-track phase through task-sized delegated runs and record both task-level and phase-level summaries.
+Execute exactly one task-sized unit for the active phase, then stop at the post-task checkpoint.
 </objective>
 
 <execution_context>

package/commands/autodev/explore-codebase.md

@@ -1,6 +1,6 @@
 ---
 name: autodev:explore-codebase
-description: Map an existing codebase, preferring parallel agents with clean fallback when unavailable
+description: Map an existing codebase, preferring foreground delegated agents with clean fallback when unavailable
 allowed-tools:
   - Read
   - Write
@@ -12,7 +12,7 @@ allowed-tools:
   - Agent
 ---
 <objective>
-Explore the current repository, use parallel codebase agents when available, and write the brownfield map into `.autodev/codebase/`.
+Explore the current repository, use foreground codebase agents when available, and write the brownfield map into `.autodev/codebase/`.
 </objective>
 
 <execution_context>

package/commands/autodev/review-phase.md

@@ -1,6 +1,6 @@
 ---
 name: autodev:review-phase
-description: Run a review pass for code quality, security, integration, and product polish, preferring parallel agents when available
+description: Run a review pass for code quality, security, integration, and product polish, preferring foreground agents when available
 argument-hint: "[phase-number]"
 allowed-tools:
   - Read

package/commands/autodev/review-task.md

@@ -0,0 +1,25 @@
+---
+name: autodev:review-task
+description: Pause after one completed task so the user can review it before any further phase execution
+argument-hint: "[phase-number]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+  - AskUserQuestion
+  - TodoWrite
+---
+<objective>
+Review one completed task and decide whether to continue execution, revise the phase, or stop here.
+</objective>
+
+<execution_context>
+@~/.claude/autodev/workflows/review-task.md
+</execution_context>
+
+<process>
+Execute the workflow in @~/.claude/autodev/workflows/review-task.md end-to-end.
+</process>

package/hooks/autodev-context-monitor.js

@@ -3,18 +3,11 @@
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+const { readProjectConfig } = require('./autodev-paths.js');
 
 const WARNING_THRESHOLD = 35;
 const CRITICAL_THRESHOLD = 20;
 
-function readProjectConfig(cwd) {
-  try {
-    return JSON.parse(fs.readFileSync(path.join(cwd, '.autodev', 'config.json'), 'utf8'));
-  } catch {
-    return null;
-  }
-}
-
 let input = '';
 const stdinTimeout = setTimeout(() => process.exit(0), 10000);
 process.stdin.setEncoding('utf8');

package/hooks/autodev-git-guard.js

@@ -1,15 +1,7 @@
 #!/usr/bin/env node
 
 const fs = require('fs');
-const path = require('path');
-
-function readProjectConfig(cwd) {
-  try {
-    return JSON.parse(fs.readFileSync(path.join(cwd, '.autodev', 'config.json'), 'utf8'));
-  } catch {
-    return null;
-  }
-}
+const { readProjectConfig } = require('./autodev-paths.js');
 
 function shouldBlock(command) {
   const blockedPatterns = [

package/hooks/autodev-paths.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+function fileExists(filePath) {
+  try {
+    return fs.existsSync(filePath);
+  } catch {
+    return false;
+  }
+}
+
+function findWorkspaceRoot(startDir) {
+  let cursor = path.resolve(startDir || process.cwd());
+  let gitRoot = null;
+
+  while (true) {
+    if (fileExists(path.join(cursor, '.autodev'))) {
+      return cursor;
+    }
+
+    if (!gitRoot && fileExists(path.join(cursor, '.git'))) {
+      gitRoot = cursor;
+    }
+
+    const parent = path.dirname(cursor);
+    if (parent === cursor) {
+      break;
+    }
+    cursor = parent;
+  }
+
+  return gitRoot || path.resolve(startDir || process.cwd());
+}
+
+function findAutodevRoot(startDir) {
+  const workspaceRoot = findWorkspaceRoot(startDir);
+  const autodevRoot = path.join(workspaceRoot, '.autodev');
+  return fileExists(autodevRoot) ? autodevRoot : null;
+}
+
+function readProjectConfig(startDir) {
+  const autodevRoot = findAutodevRoot(startDir);
+  if (!autodevRoot) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(fs.readFileSync(path.join(autodevRoot, 'config.json'), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+module.exports = {
+  findAutodevRoot,
+  findWorkspaceRoot,
+  readProjectConfig
+};

package/hooks/autodev-phase-boundary.sh

@@ -1,12 +1,41 @@
 #!/bin/bash
 
-CONFIG=".autodev/config.json"
+find_workspace_root() {
+  local cursor
+  cursor="$(pwd -P)"
+  local git_root=""
 
-if [ ! -f "$CONFIG" ]; then
-  exit 0
-fi
+  while true; do
+    if [ -d "$cursor/.autodev" ]; then
+      printf '%s\n' "$cursor"
+      return 0
+    fi
+
+    if [ -z "$git_root" ] && [ -e "$cursor/.git" ]; then
+      git_root="$cursor"
+    fi
+
+    if [ "$cursor" = "/" ]; then
+      break
+    fi
+
+    cursor="$(dirname "$cursor")"
+  done
+
+  if [ -n "$git_root" ]; then
+    printf '%s\n' "$git_root"
+    return 0
+  fi
+
+  return 1
+}
+
+WORKSPACE_ROOT="$(find_workspace_root)" || exit 0
+CONFIG="$WORKSPACE_ROOT/.autodev/config.json"
+
+[ -f "$CONFIG" ] || exit 0
 
-ENABLED=$(node -e "try{const c=require('./.autodev/config.json');process.stdout.write(c.hooks?.phase_boundary===false?'0':'1')}catch{process.stdout.write('0')}" 2>/dev/null)
+ENABLED=$(node -e "const fs=require('fs');const p=process.argv[1];try{const c=JSON.parse(fs.readFileSync(p,'utf8'));process.stdout.write(c.hooks?.phase_boundary===false?'0':'1')}catch{process.stdout.write('0')}" "$CONFIG" 2>/dev/null)
 if [ "$ENABLED" != "1" ]; then
   exit 0
 fi

package/hooks/autodev-read-guard.js

@@ -2,14 +2,7 @@
 
 const fs = require('fs');
 const path = require('path');
-
-function readProjectConfig(cwd) {
-  try {
-    return JSON.parse(fs.readFileSync(path.join(cwd, '.autodev', 'config.json'), 'utf8'));
-  } catch {
-    return null;
-  }
-}
+const { readProjectConfig } = require('./autodev-paths.js');
 
 let input = '';
 const stdinTimeout = setTimeout(() => process.exit(0), 3000);

package/hooks/autodev-session-state.sh

@@ -1,13 +1,42 @@
 #!/bin/bash
 
-CONFIG=".autodev/config.json"
-STATE=".autodev/STATE.md"
+find_workspace_root() {
+  local cursor
+  cursor="$(pwd -P)"
+  local git_root=""
 
-if [ ! -f "$CONFIG" ]; then
-  exit 0
-fi
+  while true; do
+    if [ -d "$cursor/.autodev" ]; then
+      printf '%s\n' "$cursor"
+      return 0
+    fi
+
+    if [ -z "$git_root" ] && [ -e "$cursor/.git" ]; then
+      git_root="$cursor"
+    fi
+
+    if [ "$cursor" = "/" ]; then
+      break
+    fi
+
+    cursor="$(dirname "$cursor")"
+  done
+
+  if [ -n "$git_root" ]; then
+    printf '%s\n' "$git_root"
+    return 0
+  fi
+
+  return 1
+}
+
+WORKSPACE_ROOT="$(find_workspace_root)" || exit 0
+CONFIG="$WORKSPACE_ROOT/.autodev/config.json"
+STATE="$WORKSPACE_ROOT/.autodev/STATE.md"
+
+[ -f "$CONFIG" ] || exit 0
 
-ENABLED=$(node -e "try{const c=require('./.autodev/config.json');process.stdout.write(c.hooks?.session_state===false?'0':'1')}catch{process.stdout.write('0')}" 2>/dev/null)
+ENABLED=$(node -e "const fs=require('fs');const p=process.argv[1];try{const c=JSON.parse(fs.readFileSync(p,'utf8'));process.stdout.write(c.hooks?.session_state===false?'0':'1')}catch{process.stdout.write('0')}" "$CONFIG" 2>/dev/null)
 if [ "$ENABLED" != "1" ]; then
   exit 0
 fi

package/hooks/autodev-statusline.js

@@ -3,19 +3,12 @@
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+const { findAutodevRoot } = require('./autodev-paths.js');
 
 function readStateFields(cwd) {
   try {
-    let cursor = cwd;
-    let statePath = null;
-    while (cursor && cursor !== path.dirname(cursor)) {
-      const candidate = path.join(cursor, '.autodev', 'STATE.md');
-      if (fs.existsSync(candidate)) {
-        statePath = candidate;
-        break;
-      }
-      cursor = path.dirname(cursor);
-    }
+    const autodevRoot = findAutodevRoot(cwd);
+    const statePath = autodevRoot ? path.join(autodevRoot, 'STATE.md') : null;
 
     if (!statePath) {
       return {

package/hooks/autodev-workflow-guard.js

@@ -1,15 +1,7 @@
 #!/usr/bin/env node
 
-const fs = require('fs');
 const path = require('path');
-
-function readProjectConfig(cwd) {
-  try {
-    return JSON.parse(fs.readFileSync(path.join(cwd, '.autodev', 'config.json'), 'utf8'));
-  } catch {
-    return null;
-  }
-}
+const { readProjectConfig } = require('./autodev-paths.js');
 
 let input = '';
 const stdinTimeout = setTimeout(() => process.exit(0), 3000);

package/package.json

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