@mthanhlm/autodev 0.3.5 → 0.3.7

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

package/README.md

@@ -8,8 +8,8 @@
 - 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
+- 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`
@@ -89,7 +89,7 @@ project -> track -> phase -> tasks
 
 - Large phases are too big for one uninterrupted execution context
 - Developers need control over what changes next
-- Each task can run in a fresh background agent context
+- Each task can run in a fresh foreground agent context
 - The main `/autodev` session stays small and orchestration-focused
 
 ### Execution Model
@@ -98,10 +98,10 @@ project -> track -> phase -> tasks
 - A phase is planned into one phase overview plus multiple task files
 - `/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 worker agent in the background
-- After each task, the worker reports back with files changed, verification, and blockers
+- 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
 - 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
 
 ## Git Policy

package/agents/autodev-codebase-domain.md

@@ -2,6 +2,8 @@
 name: autodev-codebase-domain
 description: Product and domain mapper for brownfield exploration. Use proactively when mapping an existing codebase and writing `.autodev/codebase/domain.md`.
 tools: Read, Grep, Glob, Bash, Write
+background: false
+color: purple
 model: inherit
 ---
 

package/agents/autodev-codebase-quality.md

@@ -2,6 +2,8 @@
 name: autodev-codebase-quality
 description: Testing and technical-debt mapper for brownfield exploration. Use proactively when mapping an existing codebase and writing `.autodev/codebase/quality.md`.
 tools: Read, Grep, Glob, Bash, Write
+background: false
+color: yellow
 model: inherit
 ---
 

package/agents/autodev-codebase-runtime.md

@@ -2,6 +2,8 @@
 name: autodev-codebase-runtime
 description: Runtime and dependency mapper for brownfield exploration. Use proactively when mapping an existing codebase and writing `.autodev/codebase/runtime.md`.
 tools: Read, Grep, Glob, Bash, Write
+background: false
+color: blue
 model: inherit
 ---
 

package/agents/autodev-codebase-structure.md

@@ -2,6 +2,8 @@
 name: autodev-codebase-structure
 description: Repository structure mapper for brownfield exploration. Use proactively when mapping an existing codebase and writing `.autodev/codebase/structure.md`.
 tools: Read, Grep, Glob, Bash, Write
+background: false
+color: cyan
 model: inherit
 ---
 

package/agents/autodev-review-integration.md

@@ -2,6 +2,8 @@
 name: autodev-review-integration
 description: Integration review specialist for executed phases. Use proactively after code changes to find cross-module regressions and wiring mistakes.
 tools: Read, Grep, Glob, Bash
+background: false
+color: orange
 model: inherit
 ---
 

package/agents/autodev-review-polish.md

@@ -2,6 +2,8 @@
 name: autodev-review-polish
 description: Product polish review specialist for executed phases. Use proactively after code changes to find rough UX, copy, and finish issues.
 tools: Read, Grep, Glob, Bash
+background: false
+color: pink
 model: inherit
 ---
 

package/agents/autodev-review-quality.md

@@ -2,6 +2,8 @@
 name: autodev-review-quality
 description: Quality review specialist for executed phases. Use proactively after code changes to find correctness, maintainability, and test issues.
 tools: Read, Grep, Glob, Bash
+background: false
+color: green
 model: inherit
 ---
 

package/agents/autodev-review-security.md

@@ -2,6 +2,8 @@
 name: autodev-review-security
 description: Security review specialist for executed phases. Use proactively after code changes to find auth, input-handling, and trust-boundary issues.
 tools: Read, Grep, Glob, Bash
+background: false
+color: red
 model: inherit
 ---
 

package/agents/autodev-task-worker.md

@@ -1,7 +1,9 @@
 ---
 name: autodev-task-worker
-description: Single-task implementation worker for autodev phases. Use proactively when one `.autodev` task should run in a fresh agent context and produce its matching `TASK-NN-SUMMARY.md`.
+description: Single-task implementation specialist for autodev phases. Use proactively when one `.autodev` task should run in a fresh foreground agent context and produce its matching `TASK-NN-SUMMARY.md`.
 tools: Read, Grep, Glob, Bash, Edit, Write
+background: false
+color: orange
 model: inherit
 ---
 

package/autodev/bin/autodev-tools.cjs

@@ -10,7 +10,7 @@ const DEFAULT_CONFIG = {
   workflow: {
     research: false,
     review_after_execute: true,
-    codebase_parallel_agents: 4
+    codebase_parallel_agents: 1
   },
   execution: {
     parallel: false
@@ -257,6 +257,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 [];
@@ -396,19 +425,41 @@ 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') {
+      return currentStatePhase;
+    }
     return phases.find(phase => phase.planExists && !phase.summaryExists) || 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 +521,7 @@ function buildRoute(cwd) {
   }
 
   const phases = listPhases(cwd, activeTrack);
+  const trackState = readStateSnapshot(track.state);
   if (phases.length === 0) {
     return {
       kind: 'track_setup',
@@ -481,6 +533,72 @@ 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 === '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 {

package/autodev/templates/config.json

@@ -5,7 +5,7 @@
   "workflow": {
     "research": false,
     "review_after_execute": true,
-    "codebase_parallel_agents": 4
+    "codebase_parallel_agents": 1
   },
   "execution": {
     "parallel": false

package/autodev/templates/plan.md

@@ -33,7 +33,7 @@ Type: [feature|bugfix|refactor|research|polish]
 | 02 | pending | 01 | [Concrete task goal] |
 
 ## Notes
-- [Anything the worker agents must know]
+- [Anything the delegated agents must know]
 
 ## Git Policy
 - Read-only only.

package/autodev/workflows/autodev.md

@@ -26,7 +26,7 @@ node "$AUTODEV_ROOT/autodev/bin/autodev-tools.cjs" status
    - `explore_codebase`: load and perform the explore-codebase workflow.
    - `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 worker agent first and falling back cleanly when agent delegation is unavailable.
+   - `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.
    - `review_phase`: load and perform the review-phase workflow.
    - `verify_phase`: load and perform the verify-work workflow.
 

package/autodev/workflows/execute-phase.md

@@ -1,5 +1,5 @@
 <purpose>
-Execute an active-track phase through task-sized worker runs, keep the main session orchestration-focused, and capture both task summaries and the final phase summary.
+Execute an active-track phase through task-sized delegated runs, keep the main session orchestration-focused, and capture both task summaries and the final phase summary.
 </purpose>
 
 <rules>
@@ -8,11 +8,12 @@ Execute an active-track phase through task-sized worker runs, keep the main sess
 - Stay within the current phase. Do not silently expand scope.
 - Execute one task at a time by default.
 - Do not use waves.
-- Prefer a fresh background worker for each task so the phase session does not bloat.
+- Prefer a fresh foreground agent for each task so the phase session does not bloat.
 - If agent delegation is available in this environment, delegate task implementation.
 - If a delegation attempt fails with an environment limitation like `specialized agents aren't available`, treat agent delegation as unavailable for this run and continue cleanly.
 - The main phase session should remain orchestration-focused whenever delegation works.
 - The main phase session may update `.autodev/` state and aggregate phase artifacts.
+- Do not run autodev subagents as background tasks.
 </rules>
 
 <process>
@@ -54,6 +55,8 @@ node "$AUTODEV_ROOT/autodev/bin/autodev-tools.cjs" init execute-phase "$ARGUMENT
    - `autodev-task-worker` when autodev is installed into `.claude/`
    - `autodev:autodev-task-worker` only when this workflow is being run directly from a plugin directory
 
+   Run it in the foreground as part of the current workflow step.
+
    Tell the subagent:
    - phase path
    - task path
@@ -65,12 +68,12 @@ 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
 
-9. After the worker returns, or after the current-session fallback completes:
+9. After the delegated agent returns, or after the current-session fallback completes:
    - confirm `TASK-NN-SUMMARY.md` exists
    - inspect whether the task is done or blocked
    - report the result to the user
@@ -110,10 +113,11 @@ node "$AUTODEV_ROOT/autodev/bin/autodev-tools.cjs" init execute-phase "$ARGUMENT
 
 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.
 </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

@@ -14,13 +14,13 @@ 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 worker agent per task, and writes `TASK-NN-SUMMARY.md` plus the final `NN-SUMMARY.md`.
+  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`.
 - `/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`

package/autodev/workflows/new-project.md

@@ -31,7 +31,7 @@ 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`
+   - `workflow.codebase_parallel_agents: 1`
    - `execution.parallel: false`
    - `git.mode: "read-only"`
 

package/autodev/workflows/plan-phase.md

@@ -1,5 +1,5 @@
 <purpose>
-Create one practical phase plan for the active track, then break it into reviewable task files that are small enough for fresh worker-agent execution.
+Create one practical phase plan for the active track, then break it into reviewable task files that are small enough for fresh foreground-agent execution.
 </purpose>
 
 <rules>
@@ -58,7 +58,7 @@ TASK-02.md
 ```
 
 Each task should be:
-   - small enough for one fresh worker agent context
+   - small enough for one fresh delegated agent context
    - clear about likely files to touch
    - explicit about verification
    - reviewable as a standalone unit

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/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/commands/autodev/execute-phase.md

@@ -1,6 +1,6 @@
 ---
 name: autodev:execute-phase
-description: Execute an active-track phase task by task, preferring fresh background workers with clean fallback when unavailable
+description: Execute an active-track phase task by task, preferring fresh foreground agents 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 worker runs and record both task-level and phase-level summaries.
+Execute one active-track phase through task-sized delegated runs and record both task-level and phase-level summaries.
 </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/package.json

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