@mthanhlm/autodev 0.4.1 → 0.4.3

package/.claude-plugin/plugin.json

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

package/README.md

@@ -8,9 +8,11 @@
 - Keeps project state in `.autodev/`
 - Uses `/autodev` as the main command
 - Organizes work as `project -> track -> phase -> tasks`
+- Starts new projects and new tracks with a short discovery pass so requirements are based on the user's actual goal
 - 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
+- Maps brownfield repos in the main session, with optional specialized helpers when the environment supports them
 - Runs a multi-lens review pass, using foreground review agents when the environment supports them
+- Can auto-format edited code after Claude writes files when a local formatter is available
 - Ships manual commands when you want direct control:
   - `/autodev-help`
   - `/autodev-new-project`
@@ -105,6 +107,7 @@ project -> track -> phase -> tasks
 ### Execution Model
 
 - `/autodev` remains the single entrypoint
+- Project and track setup should clarify what the user wants to build, for whom, and what done looks like before writing state files
 - 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
@@ -116,6 +119,7 @@ project -> track -> phase -> tasks
 - No automatic parallel execution
 - If specialized agents are unavailable in the current Claude Code environment, the workflow falls back cleanly to current-session execution instead of stopping on platform wording
 - If you want Claude Code itself to hard-disable background task functionality, install with `--disable-background-tasks`, which writes `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1` into Claude Code `settings.json`
+- The post-edit formatter hook uses only locally available tools such as `prettier`, `ruff`, `black`, `gofmt`, `rustfmt`, or `shfmt`, and skips `.autodev/` files
 
 ## Git Policy
 

package/autodev/bin/autodev-tools.cjs

@@ -16,6 +16,7 @@ const DEFAULT_CONFIG = {
     mode: 'read-only'
   },
   hooks: {
+    auto_format: true,
     context_warnings: true,
     read_guard: true,
     workflow_guard: true,

package/autodev/templates/config.json

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

package/autodev/templates/track.md

@@ -3,8 +3,15 @@
 Type: [feature|bugfix|refactor|research|polish]
 Status: active
 
+## Why This Track
+[Why this work matters right now.]
+
 ## Outcome
-[What this track is trying to achieve.]
+[What changes for the user or operator when this track is done.]
+
+## Success Signals
+- [Observable user or operator outcome]
+- [Verification or quality bar]
 
 ## Scope Boundaries
 - [What is in scope]

package/autodev/workflows/autodev.md

@@ -37,13 +37,22 @@ node "$AUTODEV_ROOT/autodev/bin/autodev-tools.cjs" status
 
 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.
+   - When creating or repairing a track, do a short track-discovery pass before writing files.
+   - Ask for:
+     - the initiative name
+     - what the user wants to ship or change in this track
+     - what done looks like
+     - scope boundaries and explicit non-goals
+     - dependencies or constraints only if they affect planning
+   - If the request is vague, summarize the understanding in a few bullets and resolve ambiguity before writing.
+   - If no tracks exist, do not jump straight to phase types before the track goal is clear.
    - Create or repair:
      - `.autodev/ACTIVE_TRACK`
      - `.autodev/tracks/<slug>/TRACK.md`
      - `.autodev/tracks/<slug>/REQUIREMENTS.md`
      - `.autodev/tracks/<slug>/ROADMAP.md`
      - `.autodev/tracks/<slug>/STATE.md`
+   - Fill the track and requirements docs from the clarified intent, not generic placeholders.
    - Use a lowercase hyphenated slug.
    - Use roadmap headings in this format:
 

package/autodev/workflows/explore-codebase.md

@@ -3,8 +3,11 @@ Map a brownfield repository quickly and produce a usable codebase brief without
 </purpose>
 
 <rules>
-- Prefer a small set of foreground codebase agents, run one at a time, when agent delegation is available.
+- The main `/autodev` session owns this workflow and the final synthesis.
+- Specialized codebase agents are optional implementation helpers, not a separate user-facing mode.
+- Prefer a small set of foreground codebase agents, run one at a time, only when agent delegation is clearly available.
 - Give each agent a disjoint write target.
+- If agent delegation is unavailable or unclear, continue inline without surfacing platform confusion.
 - Use read-only investigation only. No git writes.
 - Focus on information that will improve planning and execution for the active track.
 </rules>
@@ -26,34 +29,36 @@ 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 agent delegation is available, explicitly call the `Agent` tool for these subagents, one at a time in the foreground, with owned outputs:
+4. Do a small amount of direct repo reading first so the current session understands the workspace before deciding whether helper agents are useful.
+
+5. If agent delegation is clearly 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`
    - `autodev-codebase-quality` for standalone installs, or `autodev:autodev-codebase-quality` in direct plugin runs, owns `.autodev/codebase/quality.md`
 
-5. Tell each agent:
+6. Tell each agent:
    - it is not alone in the codebase
    - it must not overwrite another agent's file
    - it should stay read-only except for its owned output file
    - it should prefer concise, decision-useful findings over exhaustive listing
 
-6. If agent delegation is unavailable, do not stop on the raw platform message.
+7. 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:
+8. 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
 
-8. Update `.autodev/STATE.md` and the active track `STATE.md` so they reflect:
+9. Update `.autodev/STATE.md` and the active track `STATE.md` so they reflect:
    - `Current Step: planning`
    - `Next Command: /autodev`
    - refreshed ISO timestamp
 
-9. End with:
+10. End with:
    - the biggest structural insight
    - the biggest risk
    - `/autodev` as the next command

package/autodev/workflows/help.md

@@ -2,6 +2,7 @@
 
 Lean Claude Code workflow. No automatic commits. No branches. No worktrees. Git is read-only.
 It resolves `.autodev/` state from the repo root even when you start Claude in a nested subdirectory.
+It can auto-format edited code after writes when the repo already has a local formatter available.
 
 ## Main Entry
 

package/autodev/workflows/new-project.md

@@ -5,7 +5,8 @@ Initialize `.autodev/` with useful project-level context, then create the first
 <rules>
 - Do not run `git init`, `git add`, `git commit`, `git checkout`, `git switch`, `git merge`, `git rebase`, `git worktree`, `git push`, `git pull`, `git stash`, `git reset`, `git fetch`, or `git clone`.
 - Git is read-only only.
-- Use concise questioning. Ask only for details that materially change requirements or roadmap.
+- Use concise questioning, but do a short discovery pass before writing project state.
+- Ask only for details that materially change requirements or roadmap.
 - Treat the repository as a `project`, then put the current initiative in a `track`.
 </rules>
 
@@ -19,11 +20,15 @@ node "$AUTODEV_ROOT/autodev/bin/autodev-tools.cjs" init new-project
 
 2. If `.autodev/PROJECT.md` already exists, stop and tell the user to use `/autodev`.
 
-3. If the current prompt does not provide enough information, ask only for:
-   - the product or repository purpose
-   - whether this is greenfield or brownfield if ambiguous
-   - the first track name and desired outcome
-   - hard constraints only if they materially affect planning
+3. Do a short discovery pass before writing project or track files.
+   - If the current prompt is thin, ask for:
+     - what the user wants to build or change right now
+     - who it is for or what pain it solves
+     - what done looks like for the first track
+     - scope boundaries, constraints, and explicit non-goals that materially affect planning
+     - whether this is greenfield or brownfield if ambiguous
+   - Prefer one compact batch of questions over a long drip of follow-ups.
+   - Reflect the understanding back in 2-5 bullets before writing files when the original request was vague.
 
 4. Read the templates from the execution context.
 
@@ -32,11 +37,13 @@ node "$AUTODEV_ROOT/autodev/bin/autodev-tools.cjs" init new-project
    - `workflow.research: false`
    - `workflow.review_after_execute: true`
    - `git.mode: "read-only"`
+   - `hooks.auto_format: true`
 
 6. Write `.autodev/PROJECT.md` with:
    - one-line summary
    - project type
    - repo or product problem
+   - current user goal or job to be done
    - users or operators
    - success criteria
    - constraints
@@ -57,12 +64,14 @@ node "$AUTODEV_ROOT/autodev/bin/autodev-tools.cjs" init new-project
 9. Create `.autodev/tracks/<slug>/TRACK.md` with:
    - track name
    - type or workstream shape
-   - desired outcome
-   - scope boundaries
+   - why this track exists now
+   - desired outcome and what done looks like
+   - scope boundaries and explicit non-goals
    - known dependencies
    - brownfield notes if this is an existing repo
 
 10. Write `.autodev/tracks/<slug>/REQUIREMENTS.md` with clear must-have requirements and acceptance bullets for the track only.
+   Tie the acceptance bullets to the discovered outcome instead of placeholder implementation tasks.
 
 11. Write `.autodev/tracks/<slug>/ROADMAP.md` with 2-8 phases using this exact heading format:
 
@@ -88,5 +97,5 @@ Each phase must include:
 
 13. If the project is brownfield, do not fake a codebase map. Continue into codebase exploration inside `/autodev` by default. Mention `/autodev-explore-codebase` only as a manual shortcut. Otherwise, the next step is planning phase 1 through `/autodev`.
 
-14. End with a short summary and direct the user to `/autodev`. Mention the manual shortcut only if useful.
+14. End with a short summary of what the user wants to build or change and direct the user to `/autodev`. Mention the manual shortcut only if useful.
 </process>

package/bin/install.js

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

package/hooks/autodev-auto-format.js

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

package/hooks/hooks.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mthanhlm/autodev",
-  "version": "0.4.1",
+  "version": "0.4.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"