@mthanhlm/autodev 0.4.4 → 0.5.0

package/commands/autodev/index.md

@@ -1,7 +1,7 @@
 ---
 name: autodev
-description: Route the project through the next useful autodev step from a single entrypoint
-argument-hint: "[goal, track, or question]"
+description: Truthful checkpointed workflow with durable context, one active plan, and hard verification gates
+argument-hint: "[goal or correction]"
 allowed-tools:
   - Read
   - Write
@@ -11,17 +11,125 @@ allowed-tools:
   - Glob
   - TodoWrite
   - AskUserQuestion
-  - Agent
-  - WebFetch
 ---
 <objective>
-Use `/autodev` as the default command. Inspect `.autodev/` state, route automatically, and execute the right workflow end-to-end.
+Use `/autodev` as the single entrypoint. Keep durable context in `.autodev/`, treat `.autodev/state.json` as the only machine state, and never claim work is done without evidence.
 </objective>
 
-<execution_context>
-@~/.claude/autodev/workflows/autodev.md
-</execution_context>
+<principles>
+- `state.json` is authoritative machine state. Never edit it directly. Use the CLI update commands.
+- `brief.md`, `context.md`, `plan.md`, and `runs/*.md` are human-readable artifacts and may be edited directly.
+- Global install disables Claude background tasks. Do not rely on them.
+- Keep work bounded to one plan item per run unless the work is trivial and fully verified.
+- If evidence is missing, say so plainly and stop.
+- Git is read-only.
+</principles>
+
+<templates>
+@~/.claude/autodev/templates/brief.md
+@~/.claude/autodev/templates/context.md
+@~/.claude/autodev/templates/plan.md
+@~/.claude/autodev/templates/run.md
+</templates>
 
 <process>
-Execute the router workflow in @~/.claude/autodev/workflows/autodev.md end-to-end.
+1. Bootstrap and inspect status:
+
+```bash
+AUTODEV_ROOT="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude}"
+node "$AUTODEV_ROOT/autodev/bin/autodev-tools.cjs" bootstrap
+node "$AUTODEV_ROOT/autodev/bin/autodev-tools.cjs" status
+```
+
+2. Route by `route.kind`:
+   - `init_brief`
+     - Inspect the repo first.
+     - Ask concise questions only if the goal, user, constraints, or done definition are still unclear.
+     - Write `.autodev/brief.md` from the template.
+     - Then run:
+
+```bash
+node "$AUTODEV_ROOT/autodev/bin/autodev-tools.cjs" update --stage planning --project-type <brownfield|greenfield> --touch
+```
+
+   - `build_context`
+     - Brownfield only.
+     - Read only the repo areas needed to orient the next change.
+     - Write `.autodev/context.md` as a concise snapshot of architecture, entrypoints, constraints, safe change points, and risk hotspots.
+     - Then run:
+
+```bash
+node "$AUTODEV_ROOT/autodev/bin/autodev-tools.cjs" update --stage planning --touch
+```
+
+   - `plan`
+     - Read `brief.md`, `context.md` if present, and relevant repo files.
+     - Write `.autodev/plan.md` from the template with 3-7 items maximum.
+     - Every item must keep this format:
+       - `## Item NN: Title`
+       - `Status: pending|in_progress|done|blocked`
+       - `Goal: ...`
+       - `Files:` bullet list
+       - `Acceptance:` bullet list
+       - `Verification:` bullet list
+     - Make verification concrete. If no concrete verification exists, say so in the plan.
+     - Then run:
+
+```bash
+node "$AUTODEV_ROOT/autodev/bin/autodev-tools.cjs" update --stage execution --current-item 01 --touch
+```
+
+   - `repair_plan`
+     - Read the blocked item, the last run report, and relevant code.
+     - Update only the remaining plan items needed to recover.
+     - Preserve already-done items.
+     - Keep the plan small.
+     - Then run:
+
+```bash
+node "$AUTODEV_ROOT/autodev/bin/autodev-tools.cjs" update --stage execution --touch
+```
+
+   - `execute`
+     - Read the current item from `status.plan_items`.
+     - Tell the user what item you are doing, likely files, and verification plan.
+     - Update the item status in `plan.md` to `in_progress` before editing code if it was still `pending`.
+     - Make only the code changes needed for that item.
+     - Run the verification listed in the item.
+     - Create a run log skeleton:
+
+```bash
+node "$AUTODEV_ROOT/autodev/bin/autodev-tools.cjs" create-run execute
+```
+
+     - Fill the run report with:
+       - `Observed` facts only
+       - `Inferred` only when unavoidable
+       - files changed
+       - exact verification commands and results
+       - unknowns or manual gaps
+     - If verification passed, mark the plan item `done`.
+     - If verification failed or stayed incomplete, mark the item `blocked`, set `Outcome: blocked` or `Outcome: unverified` in the run log, and stop.
+     - Update machine state with the run path and the result:
+
+```bash
+node "$AUTODEV_ROOT/autodev/bin/autodev-tools.cjs" update --stage <execution|blocked|complete> --current-item <NN|none> --last-result <observed|blocked|unverified> --last-run-path <path>
+```
+
+     - Re-run `status` once after the update to keep the next route honest.
+     - Stop after one item unless the next step is trivial and already verified in the same run.
+
+   - `complete`
+     - Summarize the finished plan truthfully.
+     - Call out any manual follow-up or residual risk.
+
+3. Never say `done` unless you have:
+   - observed verification output, or
+   - explicit user confirmation for a manual check.
+
+4. Use these labels in summaries when the work is non-trivial:
+   - `Observed`
+   - `Inferred`
+   - `Unverified`
+   - `Blocked`
 </process>

package/commands/autodev/status.md

@@ -0,0 +1,22 @@
+---
+name: autodev:status
+description: Show the current durable autodev state and next route
+allowed-tools:
+  - Bash
+  - Read
+---
+<objective>
+Render the current autodev status from `.autodev/state.json`, `brief.md`, `context.md`, and `plan.md`.
+</objective>
+
+<process>
+1. Run:
+
+```bash
+AUTODEV_ROOT="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude}"
+node "$AUTODEV_ROOT/autodev/bin/autodev-tools.cjs" bootstrap
+node "$AUTODEV_ROOT/autodev/bin/autodev-tools.cjs" status table
+```
+
+2. Output the table directly.
+</process>

package/hooks/autodev-auto-format.js

@@ -3,7 +3,7 @@
 const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
-const { findWorkspaceRoot, readProjectConfig } = require('./autodev-paths.js');
+const { findWorkspaceRoot, readAutodevState } = require('./autodev-paths.js');
 
 const PRETTIER_EXTENSIONS = new Set([
   '.js', '.jsx', '.cjs', '.mjs',
@@ -168,8 +168,8 @@ try {
 
   const cwd = data.cwd || process.cwd();
   const workspaceRoot = findWorkspaceRoot(cwd);
-  const config = readProjectConfig(cwd);
-  if (config && config.hooks?.auto_format === false) {
+  const state = readAutodevState(cwd);
+  if (state && state.settings?.auto_format === false) {
     process.exit(0);
   }
 

package/hooks/autodev-git-guard.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 const fs = require('fs');
-const { readProjectConfig } = require('./autodev-paths.js');
+const { readAutodevState } = require('./autodev-paths.js');
 
 function shouldBlock(command) {
   const blockedPatterns = [
@@ -17,17 +17,16 @@ function shouldBlock(command) {
   return blockedPatterns.some(pattern => pattern.test(command));
 }
 
-let input = '';
 try {
-  input = fs.readFileSync(0, 'utf8');
+  const input = fs.readFileSync(0, 'utf8');
   const data = JSON.parse(input);
   if (data.tool_name !== 'Bash') {
     process.exit(0);
   }
 
   const cwd = data.cwd || process.cwd();
-  const config = readProjectConfig(cwd);
-  if (!config || config.git?.mode !== 'read-only' || config.hooks?.git_guard === false) {
+  const state = readAutodevState(cwd);
+  if (!state || state.settings?.git_mode !== 'read-only') {
     process.exit(0);
   }
 
@@ -38,8 +37,7 @@ try {
 
   fs.writeSync(1, `${JSON.stringify({
     decision: 'block',
-    reason:
-      'autodev git policy is read-only. Allowed examples: git status, git diff, git log, git show, git rev-parse, git ls-files, git branch --show-current.'
+    reason: 'autodev git policy is read-only. Allowed examples: git status, git diff, git log, git show, git rev-parse, git ls-files, git branch --show-current.'
   })}\n`);
   process.exit(2);
 } catch {

package/hooks/autodev-paths.js

@@ -40,14 +40,14 @@ function findAutodevRoot(startDir) {
   return fileExists(autodevRoot) ? autodevRoot : null;
 }
 
-function readProjectConfig(startDir) {
+function readAutodevState(startDir) {
   const autodevRoot = findAutodevRoot(startDir);
   if (!autodevRoot) {
     return null;
   }
 
   try {
-    return JSON.parse(fs.readFileSync(path.join(autodevRoot, 'config.json'), 'utf8'));
+    return JSON.parse(fs.readFileSync(path.join(autodevRoot, 'state.json'), 'utf8'));
   } catch {
     return null;
   }
@@ -56,5 +56,5 @@ function readProjectConfig(startDir) {
 module.exports = {
   findAutodevRoot,
   findWorkspaceRoot,
-  readProjectConfig
+  readAutodevState
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mthanhlm/autodev",
-  "version": "0.4.4",
-  "description": "A lean Claude Code workflow system with a single entrypoint, task-based phase execution, and read-only git.",
+  "version": "0.5.0",
+  "description": "A global Claude Code plugin with durable repo context, hard verification gates, and read-only git.",
   "bin": {
     "autodev": "bin/install.js"
   },
@@ -9,7 +9,6 @@
     ".claude-plugin",
     "bin",
     "commands",
-    "agents",
     "autodev",
     "hooks",
     "scripts",
@@ -21,9 +20,9 @@
     "claude",
     "claude-code",
     "workflow",
-    "planning",
+    "durable-context",
     "brownfield",
-    "review",
+    "verification",
     "autodev"
   ],
   "author": "mthanhlm",

package/scripts/run-tests.cjs

@@ -6,11 +6,21 @@ const { spawnSync } = require('child_process');
 
 const root = path.resolve(__dirname, '..');
 const testsDir = path.join(root, 'tests');
+if (!fs.existsSync(testsDir)) {
+  process.stderr.write('run-tests: tests/ is missing\n');
+  process.exit(1);
+}
+
 const files = fs.readdirSync(testsDir)
   .filter(file => file.endsWith('.test.cjs'))
   .sort()
   .map(file => path.join(testsDir, file));
 
+if (files.length === 0) {
+  process.stderr.write('run-tests: no *.test.cjs files were found\n');
+  process.exit(1);
+}
+
 for (const file of files) {
   const result = spawnSync(process.execPath, [file], {
     cwd: root,

package/agents/autodev-codebase-domain.md

@@ -1,25 +0,0 @@
----
-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
----
-
-# autodev-codebase-domain
-
-You are responsible for `.autodev/codebase/domain.md`.
-
-## Goal
-- Explain the main product areas, user flows, and state boundaries that matter for the active track.
-
-## Rules
-- You are not alone in the codebase.
-- Do not overwrite files owned by other agents.
-- Stay read-only except for your owned output file.
-- Avoid generic architecture commentary.
-
-## Output
-- Write only `.autodev/codebase/domain.md`.
-- Cover main product areas, key flows, data boundaries, and active-track impact.

package/agents/autodev-codebase-quality.md

@@ -1,25 +0,0 @@
----
-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
----
-
-# autodev-codebase-quality
-
-You are responsible for `.autodev/codebase/quality.md`.
-
-## Goal
-- Identify testing posture, conventions, risks, and technical debt that can affect the active track.
-
-## Rules
-- You are not alone in the codebase.
-- Do not overwrite files owned by other agents.
-- Stay read-only except for your owned output file.
-- Focus on actionable risks, not style preferences.
-
-## Output
-- Write only `.autodev/codebase/quality.md`.
-- Cover tests, conventions, risks, and tech debt.

package/agents/autodev-codebase-runtime.md

@@ -1,25 +0,0 @@
----
-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
----
-
-# autodev-codebase-runtime
-
-You are responsible for `.autodev/codebase/runtime.md`.
-
-## Goal
-- Map the technical runtime surface: stack, build/run path, configuration, and external dependencies.
-
-## Rules
-- You are not alone in the codebase.
-- Do not overwrite files owned by other agents.
-- Stay read-only except for your owned output file.
-- Prefer concrete commands and files over vague summaries.
-
-## Output
-- Write only `.autodev/codebase/runtime.md`.
-- Cover stack, run/build path, config/env, and external dependencies.

package/agents/autodev-codebase-structure.md

@@ -1,25 +0,0 @@
----
-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
----
-
-# autodev-codebase-structure
-
-You are responsible for `.autodev/codebase/structure.md`.
-
-## Goal
-- Map the repository layout, entrypoints, and architecture shape in a way that helps the active track move faster.
-
-## Rules
-- You are not alone in the codebase.
-- Do not overwrite files owned by other agents.
-- Stay read-only except for your owned output file.
-- Keep the result concise and decision-useful.
-
-## Output
-- Write only `.autodev/codebase/structure.md`.
-- Cover top-level layout, entrypoints, architectural shape, and hotspots.

package/agents/autodev-review-integration.md

@@ -1,30 +0,0 @@
----
-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
----
-
-# autodev-review-integration
-
-Review the executed phase for integration and regression risk.
-
-## Focus
-- broken assumptions across modules
-- runtime wiring issues
-- migration or compatibility risk
-- missing tests for changed seams
-- likely regressions in adjacent flows
-
-## Rules
-- Stay read-only.
-- Return findings only. Do not write files.
-- Prioritize concrete cross-boundary risks.
-
-## Response Format
-- Severity
-- Evidence
-- Why it matters
-- Suggested action

package/agents/autodev-review-polish.md

@@ -1,30 +0,0 @@
----
-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
----
-
-# autodev-review-polish
-
-Review the executed phase for product polish and obvious AI-generated roughness.
-
-## Focus
-- generic or repetitive UI or copy
-- weak UX decisions
-- placeholder-looking implementation
-- inconsistent naming or interaction details
-- code or interface choices that feel obviously machine-generated and under-finished
-
-## Rules
-- Stay read-only.
-- Return findings only. Do not write files.
-- Prefer concrete examples over subjective taste.
-
-## Response Format
-- Severity
-- Evidence
-- Why it matters
-- Suggested action

package/agents/autodev-review-quality.md

@@ -1,30 +0,0 @@
----
-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
----
-
-# autodev-review-quality
-
-Review the executed phase for code quality.
-
-## Focus
-- correctness
-- maintainability
-- naming and structure
-- test quality
-- accidental complexity
-
-## Rules
-- Stay read-only.
-- Return findings only. Do not write files.
-- Report only concrete issues or explicitly say there are no blocking findings.
-
-## Response Format
-- Severity
-- Evidence
-- Why it matters
-- Suggested action

package/agents/autodev-review-security.md

@@ -1,30 +0,0 @@
----
-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
----
-
-# autodev-review-security
-
-Review the executed phase for security and misuse risks.
-
-## Focus
-- auth and authorization mistakes
-- injection or unsafe input handling
-- secret or config exposure
-- unsafe filesystem or shell behavior
-- trust boundary mistakes
-
-## Rules
-- Stay read-only.
-- Return findings only. Do not write files.
-- Avoid theoretical issues without code evidence.
-
-## Response Format
-- Severity
-- Evidence
-- Why it matters
-- Suggested action

package/agents/autodev-task-worker.md

@@ -1,39 +0,0 @@
----
-name: autodev-task-worker
-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
----
-
-# autodev-task-worker
-
-Execute one assigned task inside the current phase and report back to the main phase session.
-
-## Goal
-
-- Read the assigned phase context and task file
-- Make only the code changes needed for that task
-- Run the requested verification
-- Write the matching task summary
-
-## Rules
-
-- 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.
-
-## Output
-
-- 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
-  - verification run
-  - blocker or done

package/autodev/templates/codebase/domain.md

@@ -1,13 +0,0 @@
-# Codebase Domain
-
-## Main Product Areas
-- [Domain area]
-
-## Key User Or System Flows
-- [Flow]
-
-## Data And State Boundaries
-- [Where important state lives]
-
-## Active Track Impact
-- [How the current track intersects the domain]

package/autodev/templates/codebase/quality.md

@@ -1,13 +0,0 @@
-# Codebase Quality
-
-## Tests
-- [Existing test setup and obvious gaps]
-
-## Conventions
-- [Naming, file organization, style patterns]
-
-## Risks
-- [Security, stability, or maintainability concerns]
-
-## Tech Debt
-- [Important debt likely to affect the active track]

package/autodev/templates/codebase/runtime.md

@@ -1,13 +0,0 @@
-# Codebase Runtime
-
-## Stack
-- [Languages, frameworks, libraries]
-
-## Build And Run
-- [Commands, services, or boot path]
-
-## Configuration And Environment
-- [Env vars, config files, deployment assumptions]
-
-## External Dependencies
-- [APIs, databases, queues, or packages]

package/autodev/templates/codebase/structure.md

@@ -1,13 +0,0 @@
-# Codebase Structure
-
-## Top-Level Layout
-- [Important directories and files]
-
-## Entry Points
-- [App, server, CLI, worker, or build entry points]
-
-## Architectural Shape
-- [How the code is grouped]
-
-## Hotspots
-- [Files or modules likely to matter for the active track]

package/autodev/templates/codebase/summary.md

@@ -1,13 +0,0 @@
-# Codebase Summary
-
-## Architecture Snapshot
-- [High-level shape]
-
-## What Matters For The Active Track
-- [Most relevant subsystems]
-
-## Safe Change Points
-- [Likely low-risk places to work]
-
-## Risk Alerts
-- [Biggest planning or implementation risks]

package/autodev/templates/config.json

@@ -1,22 +0,0 @@
-{
-  "project": {
-    "type": null
-  },
-  "workflow": {
-    "research": false,
-    "review_after_execute": true
-  },
-  "git": {
-    "mode": "read-only"
-  },
-  "hooks": {
-    "auto_format": true,
-    "context_warnings": true,
-    "read_guard": true,
-    "workflow_guard": true,
-    "prompt_guard": true,
-    "git_guard": true,
-    "session_state": true,
-    "phase_boundary": true
-  }
-}