@mthanhlm/autodev 0.3.1 → 0.3.3

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 four parallel codebase agents
-- Runs a four-agent review pass after execution
+- 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
 - Ships manual commands when you want direct control:
   - `/autodev-help`
   - `/autodev-new-project`
@@ -93,10 +93,11 @@ project -> track -> phase -> tasks
 - `/autodev` remains the single entrypoint
 - A phase is planned into one phase overview plus multiple task files
 - The phase keeps one user-facing orchestration session
-- Each task is executed by a fresh worker agent in the background
+- 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
 - No waves by default
 - No parallel execution unless the user explicitly asks for it later
+- 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-task-worker.md

@@ -13,6 +13,7 @@ Execute one assigned task inside the current phase and report back to the main p
 
 - You are not alone in the codebase.
 - Stay inside the assigned task scope.
+- The main phase session should stay orchestration-focused while you own this task.
 - Do not run git write commands.
 - Do not silently expand into the next task.
 - If blocked, say so clearly and write the blocker into the task summary.
@@ -21,6 +22,7 @@ Execute one assigned task inside the current phase and report back to the main p
 
 - Update the repository code for the assigned task only.
 - Write only the assigned `TASK-NN-SUMMARY.md`.
+- Do not edit project-level or track-level state files.
 - Return a concise report:
   - task id
   - files changed

package/autodev/workflows/autodev.md

@@ -8,6 +8,7 @@ Use `/autodev` as the single entrypoint for the normal workflow. Route automatic
 - Keep the model `project -> track -> phase -> tasks`.
 - Brownfield repositories should be mapped before detailed phase planning.
 - Never run git write commands.
+- Keep router context small. Do not preload workflow files that are not selected by the current route.
 </rules>
 
 <process>
@@ -19,17 +20,19 @@ node "$HOME/.claude/autodev/bin/autodev-tools.cjs" status
 
 2. Inspect the returned `route.kind`, `project_type`, `tracks`, and active track data.
 
-3. Route as follows, and complete the selected workflow in the same turn:
-   - `init_project`: perform the new-project workflow.
-   - `explore_codebase`: perform the explore-codebase workflow.
-   - `plan_phase`: perform the plan-phase workflow.
-   - `execute_phase`: perform the execute-phase workflow, which should advance one task-sized unit in the current phase session.
-   - `review_phase`: perform the review-phase workflow.
-   - `verify_phase`: perform the verify-work workflow.
+3. Route as follows:
+   - `init_project`: read `@~/.claude/autodev/workflows/new-project.md`, then perform that workflow.
+   - `explore_codebase`: read `@~/.claude/autodev/workflows/explore-codebase.md`, then perform that workflow.
+   - `plan_phase`: read `@~/.claude/autodev/workflows/plan-phase.md`, then perform that workflow.
+   - `execute_phase`: read `@~/.claude/autodev/workflows/execute-phase.md`, then perform that workflow, which should advance one task-sized unit in the current phase session by trying a fresh task worker first and falling back cleanly when delegation is unavailable.
+   - `review_phase`: read `@~/.claude/autodev/workflows/review-phase.md`, then perform that workflow.
+   - `verify_phase`: read `@~/.claude/autodev/workflows/verify-work.md`, then perform that workflow.
 
-4. Do not stop after identifying a brownfield codebase route. If the route is `explore_codebase`, perform the exploration as part of the same `/autodev` run instead of telling the user to switch commands.
+4. Read only the workflow file needed for the selected route. Do not load the others "just in case".
 
-5. If the route is `track_select` or `track_setup`, handle it directly:
+5. Do not stop after identifying a brownfield codebase route. If the route is `explore_codebase`, perform the exploration as part of the same `/autodev` run instead of telling the user to switch commands.
+
+6. If the route is `track_select` or `track_setup`, handle it directly:
    - If tracks exist, ask whether to continue one of them or create a new track.
    - If no tracks exist, ask only for the current initiative name, desired outcome, and likely phase types.
    - Create or repair:
@@ -47,16 +50,16 @@ node "$HOME/.claude/autodev/bin/autodev-tools.cjs" status
 
    - After track setup, continue in the same turn by re-running the route logic mentally and executing the next step.
 
-6. If the route is `track_complete`, ask whether the user wants to:
+7. If the route is `track_complete`, ask whether the user wants to:
    - start a new track
    - run cleanup
    - stop here
 
-7. When the user chooses a new track at step 6, create it immediately and continue routing in the same turn.
+8. When the user chooses a new track at step 7, create it immediately and continue routing in the same turn.
 
-8. Every time you finish a routed step, keep both project-level and track-level state aligned. Default the state files to `Next Command: /autodev`.
+9. Every time you finish a routed step, keep both project-level and track-level state aligned. Default the state files to `Next Command: /autodev`.
 
-9. End with:
+10. End with:
    - what step you completed
    - the current route reason in plain language
    - `/autodev` as the default next command

package/autodev/workflows/execute-phase.md

@@ -8,7 +8,11 @@ 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.
-- Use a fresh background worker for each task so the phase session does not bloat.
+- Prefer a fresh background worker for each task so the phase session does not bloat.
+- If the `Task` tool is available and specialized agents are supported in this environment, delegate task implementation.
+- If a delegation attempt fails with an environment limitation like `specialized agents aren't available`, treat 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.
 </rules>
 
 <process>
@@ -44,20 +48,29 @@ node "$HOME/.claude/autodev/bin/autodev-tools.cjs" init execute-phase "$ARGUMENT
    - verification plan
    - any dependency note
 
-7. Spawn one fresh background worker using `autodev-task-worker` for the selected task.
+7. If the `Task` tool is available, first try to spawn one fresh background worker using `autodev-task-worker` for the selected task.
    Tell it:
    - phase path
    - task path
    - summary path to write
    - required context files to read first
+   - that it owns the task implementation and the task summary
+   - that the main session should stay orchestration-focused
    - to return a concise outcome only
 
-8. After the worker returns:
+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 background task workers are 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:
    - confirm `TASK-NN-SUMMARY.md` exists
    - inspect whether the task is done or blocked
    - report the result to the user
 
-9. If more tasks remain:
+10. If more tasks remain:
    - update project and track state to:
      - `Current Step: execution`
      - `Current Task: <next-task>`
@@ -65,7 +78,7 @@ node "$HOME/.claude/autodev/bin/autodev-tools.cjs" init execute-phase "$ARGUMENT
      - `Next Command: /autodev`
    - end by telling the user `/autodev` will continue with the next task
 
-10. If all tasks are done:
+11. If all tasks are done:
    - write or update `NN-SUMMARY.md` from the template with:
      - completed tasks
      - aggregate files changed
@@ -73,7 +86,7 @@ node "$HOME/.claude/autodev/bin/autodev-tools.cjs" init execute-phase "$ARGUMENT
      - remaining risks
      - next step
 
-11. Update the active track `STATE.md` so it points to:
+12. Update the active track `STATE.md` so it points to:
    - `Current Phase: N`
    - `Current Phase Type: <type>`
    - `Current Step: review`
@@ -82,7 +95,7 @@ node "$HOME/.claude/autodev/bin/autodev-tools.cjs" init execute-phase "$ARGUMENT
    - `Next Command: /autodev`
    - current ISO timestamp
 
-12. Update `.autodev/STATE.md` so it points to:
+13. Update `.autodev/STATE.md` so it points to:
    - `Active Track: <slug>`
    - `Current Step: review`
    - `Current Task: none`
@@ -90,12 +103,12 @@ node "$HOME/.claude/autodev/bin/autodev-tools.cjs" init execute-phase "$ARGUMENT
    - `Next Command: /autodev`
    - current ISO timestamp
 
-13. If the current task is blocked or incomplete:
+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 `Current Task: <same-task>`
    - set `Current Task Status: blocked`
    - keep `Next Command: /autodev`
 
-14. 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. 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

@@ -1,9 +1,9 @@
 <purpose>
-Map a brownfield repository quickly and use four parallel agents to produce a usable codebase brief without drifting into over-analysis.
+Map a brownfield repository quickly and produce a usable codebase brief without drifting into over-analysis.
 </purpose>
 
 <rules>
-- Always spawn four agents in parallel for this workflow.
+- Prefer four parallel agents for this workflow when specialized agents are 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.
@@ -25,7 +25,7 @@ node "$HOME/.claude/autodev/bin/autodev-tools.cjs" init explore-codebase
    - the active track docs if they exist
    - representative repo files needed to orient the exploration
 
-4. Spawn four parallel agents with these owned outputs:
+4. If specialized agents are available, spawn four parallel agents with these owned outputs:
    - `autodev-codebase-structure` owns `.autodev/codebase/structure.md`
    - `autodev-codebase-domain` owns `.autodev/codebase/domain.md`
    - `autodev-codebase-runtime` owns `.autodev/codebase/runtime.md`
@@ -37,19 +37,22 @@ node "$HOME/.claude/autodev/bin/autodev-tools.cjs" init explore-codebase
    - it should stay read-only except for its owned output file
    - it should prefer concise, decision-useful findings over exhaustive listing
 
-6. After the four agent outputs are written, review them and synthesize `.autodev/codebase/summary.md` with:
+6. If agent delegation is unavailable, do not stop on the raw platform message.
+   Treat messages like `specialized agents aren't available` as an environment limitation, tell the user exploration will continue in the current session, and write the four owned output files directly.
+
+7. After the four agent outputs are written, or after the current-session fallback writes them, review them and synthesize `.autodev/codebase/summary.md` with:
    - architectural overview
    - major constraints
    - current track implications
    - hotspots and likely safe change points
    - the next planning risks to watch
 
-7. Update `.autodev/STATE.md` and the active track `STATE.md` so they reflect:
+8. Update `.autodev/STATE.md` and the active track `STATE.md` so they reflect:
    - `Current Step: planning`
    - `Next Command: /autodev`
    - refreshed ISO timestamp
 
-8. End with:
+9. End with:
    - the biggest structural insight
    - the biggest risk
    - `/autodev` as the next command

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`
-  Spawns four parallel agents to map a brownfield repo into `.autodev/codebase/`.
+  Uses four parallel agents 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 and writes `TASK-NN-SUMMARY.md` plus the final `NN-SUMMARY.md`.
+  Orchestrates one phase task-by-task, preferring a fresh worker per task, and writes `TASK-NN-SUMMARY.md` plus the final `NN-SUMMARY.md`.
 - `/autodev-review-phase [phase]`
-  Spawns four review agents for code quality, security, integration, and polish, then writes `NN-REVIEW.md`.
+  Uses four review agents 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/review-phase.md

@@ -3,7 +3,7 @@ Run the automatic review bundle after execution so the user sees code quality, s
 </purpose>
 
 <rules>
-- Always spawn four review agents in parallel.
+- Prefer four review agents in parallel when specialized agents are 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.
@@ -27,7 +27,7 @@ node "$HOME/.claude/autodev/bin/autodev-tools.cjs" init review-phase "$ARGUMENTS
    - `NN-SUMMARY.md`
    - relevant source files and tests
 
-4. Spawn four parallel review agents:
+4. If specialized agents are available, spawn four parallel review agents:
    - `autodev-review-quality`
    - `autodev-review-security`
    - `autodev-review-integration`
@@ -39,22 +39,29 @@ node "$HOME/.claude/autodev/bin/autodev-tools.cjs" init review-phase "$ARGUMENTS
    - it should focus on clear issues, not generic commentary
    - it should report severity, evidence, and suggested action
 
-6. Synthesize the four agent responses into `NN-REVIEW.md` from the template with:
+6. If agent delegation is unavailable, do not stop on the raw platform message.
+   Treat messages like `specialized agents aren't available` as an environment limitation, tell the user review will continue in the current session, and perform the same review pass directly using the four lenses:
+   - quality
+   - security
+   - integration
+   - product polish
+
+7. Synthesize the four agent responses, or the current-session four-lens review, into `NN-REVIEW.md` from the template with:
    - grouped findings
    - blockers vs non-blockers
    - what looks solid
    - a final recommendation
 
-7. If blockers are found:
+8. If blockers are found:
    - set project and track state back to `Current Step: execution`
    - keep `Next Command: /autodev`
    - make the recommendation point back to the same phase
 
-8. If blockers are not found:
+9. If blockers are not found:
    - set project and track state to `Current Step: verification`
    - keep `Next Command: /autodev`
 
-9. End with a short review result:
+10. End with a short review result:
    - ready for verification, or
    - return to execution
    - include the manual shortcut command

package/commands/autodev/execute-phase.md

@@ -1,6 +1,6 @@
 ---
 name: autodev:execute-phase
-description: Execute an active-track phase task by task with fresh background workers and no git writes
+description: Execute an active-track phase task by task, preferring fresh background workers with clean fallback when unavailable
 argument-hint: "[phase-number]"
 allowed-tools:
   - Read

package/commands/autodev/explore-codebase.md

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

package/commands/autodev/index.md

@@ -20,14 +20,6 @@ Use `/autodev` as the default command. Inspect `.autodev/` state, route automati
 
 <execution_context>
 @~/.claude/autodev/workflows/autodev.md
-@~/.claude/autodev/workflows/new-project.md
-@~/.claude/autodev/workflows/explore-codebase.md
-@~/.claude/autodev/workflows/plan-phase.md
-@~/.claude/autodev/workflows/execute-phase.md
-@~/.claude/autodev/workflows/review-phase.md
-@~/.claude/autodev/workflows/verify-work.md
-@~/.claude/autodev/workflows/cleanup.md
-@~/.claude/autodev/workflows/progress.md
 </execution_context>
 
 <process>

package/commands/autodev/review-phase.md

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

package/package.json

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