@mthanhlm/autodev 0.1.1 → 0.2.0

package/autodev/workflows/plan-phase.md

@@ -1,5 +1,5 @@
 <purpose>
-Create one practical phase plan. Keep it concrete, small enough to execute, and free of git-write steps.
+Create one practical phase plan for the active track. Keep it concrete, small enough to execute, and free of git-write steps.
 </purpose>
 
 <rules>
@@ -16,15 +16,18 @@ Create one practical phase plan. Keep it concrete, small enough to execute, and
 node "$HOME/.claude/autodev/bin/autodev-tools.cjs" init plan-phase "$ARGUMENTS"
 ```
 
-2. If `.autodev/ROADMAP.md` does not exist, stop and tell the user to run `/autodev-new-project`.
+2. If there is no active track or no roadmap for it, stop and tell the user to run `/autodev`.
 
 3. If no phase is found, tell the user all phases already have plans and show `/autodev-progress`.
 
 4. Read:
    - `.autodev/PROJECT.md`
-   - `.autodev/REQUIREMENTS.md`
-   - `.autodev/ROADMAP.md`
    - `.autodev/STATE.md`
+   - `.autodev/codebase/summary.md` if it exists
+   - `.autodev/tracks/<active-track>/TRACK.md`
+   - `.autodev/tracks/<active-track>/REQUIREMENTS.md`
+   - `.autodev/tracks/<active-track>/ROADMAP.md`
+   - `.autodev/tracks/<active-track>/STATE.md`
    - the target phase section
    - any existing code relevant to this phase
 
@@ -33,10 +36,11 @@ node "$HOME/.claude/autodev/bin/autodev-tools.cjs" init plan-phase "$ARGUMENTS"
 6. Create the phase directory if missing:
 
 ```text
-.autodev/phases/NN-name/
+.autodev/tracks/<active-track>/phases/NN-type-name/
 ```
 
 7. Write or replace `NN-PLAN.md` from the template. The plan must include:
+   - phase type
    - goal
    - concrete implementation steps
    - likely files to touch
@@ -44,11 +48,18 @@ node "$HOME/.claude/autodev/bin/autodev-tools.cjs" init plan-phase "$ARGUMENTS"
    - manual checks
    - explicit git read-only reminder
 
-8. Update `.autodev/STATE.md` so it points to:
+8. Update the active track `STATE.md` so it points to:
    - `Current Phase: N`
+   - `Current Phase Type: <type>`
    - `Current Step: planned`
-   - `Next Command: /autodev-execute-phase N`
+   - `Next Command: /autodev`
    - current ISO timestamp
 
-9. End with a short summary and direct the user to `/autodev-execute-phase N`.
+9. Update `.autodev/STATE.md` so it points to:
+   - `Active Track: <slug>`
+   - `Current Step: planned`
+   - `Next Command: /autodev`
+   - current ISO timestamp
+
+10. End with a short summary and direct the user to `/autodev`. Mention `/autodev-execute-phase N` as the manual shortcut.
 </process>

package/autodev/workflows/progress.md

@@ -11,5 +11,7 @@ node "$HOME/.claude/autodev/bin/autodev-tools.cjs" progress table
 
 2. Output the table directly.
 
-3. If a project exists, add one short line after the table with the next recommended command.
+3. If a project exists, add one short line after the table with:
+   - `/autodev` as the default next command
+   - the routed manual shortcut from the table when useful
 </process>

package/autodev/workflows/review-phase.md

@@ -0,0 +1,59 @@
+<purpose>
+Run the automatic review bundle after execution so the user sees code quality, security, integration, and polish risks before manual verification.
+</purpose>
+
+<rules>
+- Always spawn four review agents in parallel.
+- 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.
+</rules>
+
+<process>
+1. Run:
+
+```bash
+node "$HOME/.claude/autodev/bin/autodev-tools.cjs" init review-phase "$ARGUMENTS"
+```
+
+2. If no executed phase is found, stop and direct the user to `/autodev-execute-phase`.
+
+3. Read:
+   - `.autodev/STATE.md`
+   - the active track `STATE.md`
+   - `NN-PLAN.md`
+   - `NN-SUMMARY.md`
+   - relevant source files and tests
+
+4. Spawn four parallel review agents:
+   - `autodev-review-quality`
+   - `autodev-review-security`
+   - `autodev-review-integration`
+   - `autodev-review-polish`
+
+5. Tell each review agent:
+   - it is not alone in the codebase
+   - it should stay read-only and return findings only
+   - 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:
+   - grouped findings
+   - blockers vs non-blockers
+   - what looks solid
+   - a final recommendation
+
+7. 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:
+   - set project and track state to `Current Step: verification`
+   - keep `Next Command: /autodev`
+
+9. End with a short review result:
+   - ready for verification, or
+   - return to execution
+   - include the manual shortcut command
+</process>

package/autodev/workflows/verify-work.md

@@ -1,9 +1,9 @@
 <purpose>
-Run lightweight user acceptance testing and keep the next action obvious.
+Run lightweight user acceptance testing after review and keep the next action obvious, including a clean fix-return path when verification fails.
 </purpose>
 
 <rules>
-- Verify against what the phase plan and summary claim.
+- 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.
 </rules>
@@ -15,11 +15,12 @@ Run lightweight user acceptance testing and keep the next action obvious.
 node "$HOME/.claude/autodev/bin/autodev-tools.cjs" init verify-work "$ARGUMENTS"
 ```
 
-2. If no executed phase is found, stop and direct the user to `/autodev-execute-phase`.
+2. If no reviewed phase is found, stop and direct the user to `/autodev-review-phase`.
 
 3. Read:
    - `NN-PLAN.md`
    - `NN-SUMMARY.md`
+   - `NN-REVIEW.md`
    - relevant code or UI files
 
 4. Present a short manual verification flow. Keep it one check at a time when user input is needed.
@@ -30,10 +31,19 @@ node "$HOME/.claude/autodev/bin/autodev-tools.cjs" init verify-work "$ARGUMENTS"
    - bugs or follow-up
    - recommended next step
 
-6. Update `.autodev/STATE.md`:
-   - if verification passed, move to the next phase and set `Next Command` to `/autodev-plan-phase <next>`
-   - if verification failed, keep the same phase active and set `Next Command` to `/autodev-execute-phase N`
+6. If verification fails, add a `Fix Return` section to `NN-UAT.md` with:
+   - exact failed behaviors
+   - reproduction notes
+   - the smallest acceptable fix target
+
+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`
+   - always set `Next Command: /autodev`
    - always refresh the ISO timestamp
 
-7. End with the verification result and the next command.
+8. Update `.autodev/STATE.md` with the matching project-level status and refreshed timestamp.
+
+9. End with the verification result and the next command. Mention the manual shortcut only if it helps.
 </process>

package/bin/install.js

@@ -11,6 +11,7 @@ const cyan = '\x1b[36m';
 const reset = '\x1b[0m';
 
 const MANAGED_PREFIX = 'autodev-';
+const ROOT_COMMAND = 'autodev';
 const HOOK_FILES = [
   'autodev-context-monitor.js',
   'autodev-git-guard.js',
@@ -191,19 +192,26 @@ function copyTextTree(srcDir, destDir, transform) {
   }
 }
 
+function commandNameFromSourceFile(fileName) {
+  const baseName = fileName.replace(/\.md$/, '');
+  return baseName === 'index' ? ROOT_COMMAND : `${ROOT_COMMAND}-${baseName}`;
+}
+
+function skillNameFromSourceFile(fileName, prefix) {
+  const baseName = fileName.replace(/\.md$/, '');
+  return baseName === 'index' ? prefix : `${prefix}-${baseName}`;
+}
+
 function copyCommandsAsLocal(srcDir, destDir, transform) {
-  if (fs.existsSync(destDir)) {
-    fs.rmSync(destDir, { recursive: true, force: true });
-  }
   fs.mkdirSync(destDir, { recursive: true });
 
   for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
-    const srcPath = path.join(srcDir, entry.name);
-    const destPath = path.join(destDir, entry.name);
-    if (entry.isDirectory()) {
-      copyCommandsAsLocal(srcPath, destPath, transform);
+    if (!entry.isFile() || !entry.name.endsWith('.md')) {
       continue;
     }
+
+    const srcPath = path.join(srcDir, entry.name);
+    const destPath = path.join(destDir, `${commandNameFromSourceFile(entry.name)}.md`);
     let content = fs.readFileSync(srcPath, 'utf8');
     content = transform(content);
     fs.writeFileSync(destPath, content, 'utf8');
@@ -214,7 +222,7 @@ function copyCommandsAsGlobalSkills(srcDir, skillsDir, prefix, transform) {
   fs.mkdirSync(skillsDir, { recursive: true });
 
   for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
-    if (entry.isDirectory() && entry.name.startsWith(`${prefix}-`)) {
+    if (entry.isDirectory() && (entry.name === prefix || entry.name.startsWith(`${prefix}-`))) {
       fs.rmSync(path.join(skillsDir, entry.name), { recursive: true, force: true });
     }
   }
@@ -224,8 +232,7 @@ function copyCommandsAsGlobalSkills(srcDir, skillsDir, prefix, transform) {
       continue;
     }
 
-    const baseName = entry.name.replace(/\.md$/, '');
-    const skillName = `${prefix}-${baseName}`;
+    const skillName = skillNameFromSourceFile(entry.name, prefix);
     const skillDir = path.join(skillsDir, skillName);
     fs.mkdirSync(skillDir, { recursive: true });
 
@@ -236,6 +243,25 @@ function copyCommandsAsGlobalSkills(srcDir, skillsDir, prefix, transform) {
   }
 }
 
+function copyAgents(srcDir, destDir, transform) {
+  if (!fs.existsSync(srcDir)) {
+    return;
+  }
+
+  fs.mkdirSync(destDir, { recursive: true });
+  for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+    if (!entry.isFile()) {
+      continue;
+    }
+
+    const srcPath = path.join(srcDir, entry.name);
+    const destPath = path.join(destDir, entry.name);
+    let content = fs.readFileSync(srcPath, 'utf8');
+    content = transform(content);
+    fs.writeFileSync(destPath, content, 'utf8');
+  }
+}
+
 function removeManagedSettings(settings) {
   if (settings.statusLine?.command && settings.statusLine.command.includes('autodev-statusline')) {
     delete settings.statusLine;
@@ -380,6 +406,15 @@ function removeInstalledFiles(targetDir, isGlobal) {
     fs.rmSync(supportDir, { recursive: true, force: true });
   }
 
+  const agentsDir = path.join(targetDir, 'agents');
+  if (fs.existsSync(agentsDir)) {
+    for (const entry of fs.readdirSync(agentsDir, { withFileTypes: true })) {
+      if (entry.isFile() && entry.name.startsWith(MANAGED_PREFIX) && entry.name.endsWith('.md')) {
+        fs.rmSync(path.join(agentsDir, entry.name), { force: true });
+      }
+    }
+  }
+
   const hooksDir = path.join(targetDir, 'hooks');
   for (const hookName of HOOK_FILES) {
     const hookPath = path.join(hooksDir, hookName);
@@ -392,20 +427,28 @@ function removeInstalledFiles(targetDir, isGlobal) {
     const skillsDir = path.join(targetDir, 'skills');
     if (fs.existsSync(skillsDir)) {
       for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
-        if (entry.isDirectory() && entry.name.startsWith(MANAGED_PREFIX)) {
+        if (entry.isDirectory() && (entry.name === ROOT_COMMAND || entry.name.startsWith(MANAGED_PREFIX))) {
           fs.rmSync(path.join(skillsDir, entry.name), { recursive: true, force: true });
         }
       }
     }
   } else {
-    const commandsDir = path.join(targetDir, 'commands', 'autodev');
+    const commandsDir = path.join(targetDir, 'commands');
     if (fs.existsSync(commandsDir)) {
-      fs.rmSync(commandsDir, { recursive: true, force: true });
+      for (const entry of fs.readdirSync(commandsDir, { withFileTypes: true })) {
+        if (entry.isFile() && entry.name.startsWith(ROOT_COMMAND) && entry.name.endsWith('.md')) {
+          fs.rmSync(path.join(commandsDir, entry.name), { force: true });
+        }
+      }
+    }
+    const legacyCommandsDir = path.join(commandsDir, ROOT_COMMAND);
+    if (fs.existsSync(legacyCommandsDir)) {
+      fs.rmSync(legacyCommandsDir, { recursive: true, force: true });
     }
     const skillsDir = path.join(targetDir, 'skills');
     if (fs.existsSync(skillsDir)) {
       for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
-        if (entry.isDirectory() && entry.name.startsWith(MANAGED_PREFIX)) {
+        if (entry.isDirectory() && (entry.name === ROOT_COMMAND || entry.name.startsWith(MANAGED_PREFIX))) {
           fs.rmSync(path.join(skillsDir, entry.name), { recursive: true, force: true });
         }
       }
@@ -450,12 +493,13 @@ function install(options = {}) {
   } else {
     copyCommandsAsLocal(
       path.join(srcRoot, 'commands', 'autodev'),
-      path.join(targetDir, 'commands', 'autodev'),
+      path.join(targetDir, 'commands'),
       transform
     );
   }
 
   copyTextTree(path.join(srcRoot, 'autodev'), path.join(targetDir, 'autodev'), transform);
+  copyAgents(path.join(srcRoot, 'agents'), path.join(targetDir, 'agents'), transform);
   copyTextTree(path.join(srcRoot, 'hooks'), path.join(targetDir, 'hooks'), transform);
   setExecutableBits(targetDir);
   const settingsPath = configureSettings(targetDir, isGlobal, options);
@@ -466,7 +510,7 @@ function install(options = {}) {
     if (settingsPath) {
       console.log(`  ${green}Updated${reset} ${cyan}${settingsPath}${reset}`);
     }
-    console.log(`  Run ${cyan}/autodev-help${reset} in Claude Code.`);
+    console.log(`  Run ${cyan}/autodev${reset} in Claude Code.`);
   }
 
   return { targetDir, settingsPath };
@@ -505,6 +549,7 @@ Options:
   --help        Show this help
 
 Examples:
+  npx @mthanhlm/autodev@latest
   npx @mthanhlm/autodev@latest --global
   npx @mthanhlm/autodev@latest --local
   npx @mthanhlm/autodev@latest --global --uninstall

package/commands/autodev/cleanup.md

@@ -0,0 +1,23 @@
+---
+name: autodev:cleanup
+description: Clean or archive autodev state with an interactive prompt
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - AskUserQuestion
+  - Grep
+  - Glob
+---
+<objective>
+Offer interactive cleanup choices for `.autodev/`, with archive-first behavior.
+</objective>
+
+<execution_context>
+@~/.claude/autodev/workflows/cleanup.md
+</execution_context>
+
+<process>
+Execute the workflow in @~/.claude/autodev/workflows/cleanup.md end-to-end.
+</process>

package/commands/autodev/execute-phase.md

@@ -1,6 +1,6 @@
 ---
 name: autodev:execute-phase
-description: Execute a phase plan sequentially without git writes
+description: Execute an active-track phase plan sequentially without git writes
 argument-hint: "[phase-number]"
 allowed-tools:
   - Read
@@ -13,7 +13,7 @@ allowed-tools:
   - AskUserQuestion
 ---
 <objective>
-Execute one phase plan from `.autodev/phases/` and record the result in a summary.
+Execute one active-track phase plan and record the result in a summary.
 </objective>
 
 <execution_context>

package/commands/autodev/explore-codebase.md

@@ -0,0 +1,33 @@
+---
+name: autodev:explore-codebase
+description: Map an existing codebase with four parallel agents and synthesize the result
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+  - AskUserQuestion
+  - Task
+---
+<objective>
+Explore the current repository, spawn four parallel codebase agents, and write the brownfield map into `.autodev/codebase/`.
+</objective>
+
+<execution_context>
+@~/.claude/autodev/workflows/explore-codebase.md
+@~/.claude/autodev/templates/codebase/structure.md
+@~/.claude/autodev/templates/codebase/domain.md
+@~/.claude/autodev/templates/codebase/runtime.md
+@~/.claude/autodev/templates/codebase/quality.md
+@~/.claude/autodev/templates/codebase/summary.md
+@~/.claude/autodev/agents/autodev-codebase-structure.md
+@~/.claude/autodev/agents/autodev-codebase-domain.md
+@~/.claude/autodev/agents/autodev-codebase-runtime.md
+@~/.claude/autodev/agents/autodev-codebase-quality.md
+</execution_context>
+
+<process>
+Execute the workflow in @~/.claude/autodev/workflows/explore-codebase.md end-to-end.
+</process>

package/commands/autodev/help.md

@@ -6,7 +6,7 @@ allowed-tools:
   - Bash
 ---
 <objective>
-Show the autodev command reference and the default workflow.
+Show the autodev command reference, with `/autodev` as the main entrypoint.
 </objective>
 
 <execution_context>

package/commands/autodev/index.md

@@ -0,0 +1,35 @@
+---
+name: autodev
+description: Route the project through the next useful autodev step from a single entrypoint
+argument-hint: "[goal, track, or question]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+  - TodoWrite
+  - AskUserQuestion
+  - Task
+  - WebFetch
+---
+<objective>
+Use `/autodev` as the default command. Inspect `.autodev/` state, route automatically, and execute the right workflow end-to-end.
+</objective>
+
+<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>
+Execute the router workflow in @~/.claude/autodev/workflows/autodev.md end-to-end.
+</process>

package/commands/autodev/new-project.md

@@ -1,7 +1,7 @@
 ---
 name: autodev:new-project
-description: Initialize a new autodev project with minimal ceremony
-argument-hint: "[idea or goals]"
+description: Initialize autodev project state and create the first active track
+argument-hint: "[project and current track goals]"
 allowed-tools:
   - Read
   - Write
@@ -11,16 +11,18 @@ allowed-tools:
   - Glob
 ---
 <objective>
-Create the `.autodev/` project state for a new or existing codebase without over-planning.
+Create the `.autodev/` project state for a new or existing codebase, then create the first active track.
 </objective>
 
 <execution_context>
 @~/.claude/autodev/workflows/new-project.md
 @~/.claude/autodev/templates/config.json
 @~/.claude/autodev/templates/project.md
+@~/.claude/autodev/templates/project-state.md
+@~/.claude/autodev/templates/track.md
 @~/.claude/autodev/templates/requirements.md
 @~/.claude/autodev/templates/roadmap.md
-@~/.claude/autodev/templates/state.md
+@~/.claude/autodev/templates/track-state.md
 </execution_context>
 
 <process>

package/commands/autodev/plan-phase.md

@@ -1,6 +1,6 @@
 ---
 name: autodev:plan-phase
-description: Create a practical plan for one roadmap phase
+description: Create a practical plan for one phase in the active track roadmap
 argument-hint: "[phase-number]"
 allowed-tools:
   - Read
@@ -12,7 +12,7 @@ allowed-tools:
   - WebFetch
 ---
 <objective>
-Create or update a single executable phase plan under `.autodev/phases/`.
+Create or update a single executable phase plan under the active track in `.autodev/tracks/<track>/phases/`.
 </objective>
 
 <execution_context>

package/commands/autodev/progress.md

@@ -6,7 +6,7 @@ allowed-tools:
   - Bash
 ---
 <objective>
-Render the current `.autodev/` progress and next recommended command.
+Render the current `.autodev/` progress, active track, and next recommended route.
 </objective>
 
 <execution_context>

package/commands/autodev/review-phase.md

@@ -0,0 +1,29 @@
+---
+name: autodev:review-phase
+description: Run a four-agent review pass for code quality, security, integration, and product polish
+argument-hint: "[phase-number]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+  - Task
+---
+<objective>
+Run the automatic review bundle for one executed phase and write a single review artifact.
+</objective>
+
+<execution_context>
+@~/.claude/autodev/workflows/review-phase.md
+@~/.claude/autodev/templates/review.md
+@~/.claude/autodev/agents/autodev-review-quality.md
+@~/.claude/autodev/agents/autodev-review-security.md
+@~/.claude/autodev/agents/autodev-review-integration.md
+@~/.claude/autodev/agents/autodev-review-polish.md
+</execution_context>
+
+<process>
+Execute the workflow in @~/.claude/autodev/workflows/review-phase.md end-to-end.
+</process>

package/commands/autodev/verify-work.md

@@ -1,6 +1,6 @@
 ---
 name: autodev:verify-work
-description: Run lightweight user acceptance testing for a phase
+description: Run lightweight user acceptance testing for a reviewed phase
 argument-hint: "[phase-number]"
 allowed-tools:
   - Read
@@ -11,7 +11,7 @@ allowed-tools:
   - Glob
 ---
 <objective>
-Record manual verification for one phase and keep the next step clear.
+Record manual verification for one reviewed phase and keep the next step clear, including gap recovery when needed.
 </objective>
 
 <execution_context>

package/hooks/autodev-session-state.sh

@@ -18,5 +18,5 @@ echo ""
 if [ -f "$STATE" ]; then
   head -20 "$STATE"
 else
-  echo "No .autodev/STATE.md yet. Start with /autodev-new-project."
+  echo "No .autodev/STATE.md yet. Start with /autodev."
 fi

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@mthanhlm/autodev",
-  "version": "0.1.1",
-  "description": "A lean Claude Code workflow system for planning and shipping without automatic git writes.",
+  "version": "0.2.0",
+  "description": "A lean Claude Code workflow system with a single entrypoint, brownfield codebase mapping, and read-only git.",
   "bin": {
     "autodev": "bin/install.js"
   },
   "files": [
     "bin",
     "commands",
+    "agents",
     "autodev",
     "hooks",
     "scripts",
@@ -20,6 +21,8 @@
     "claude-code",
     "workflow",
     "planning",
+    "brownfield",
+    "review",
     "autodev"
   ],
   "author": "mthanhlm",