@mthanhlm/autodev 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mthanhlm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PUBLISH.md

@@ -0,0 +1,75 @@
+# Publishing `@mthanhlm/autodev`
+
+## One-Time Setup
+
+1. Make sure the npm account `mthanhlm` has access to the `@mthanhlm` scope.
+2. Log in:
+
+```bash
+npm login
+```
+
+3. Verify the active account:
+
+```bash
+npm whoami
+```
+
+## Pre-Publish Checklist
+
+```bash
+cd autodev
+npm test
+npm pack
+```
+
+Check the tarball contents:
+
+```bash
+tar -tf mthanhlm-autodev-0.1.0.tgz
+```
+
+## First Public Publish
+
+Scoped packages are private by default. The first public release must include `--access public`.
+
+```bash
+npm publish --access public
+```
+
+## Later Releases
+
+1. Bump the version in `package.json`.
+2. Regenerate the tarball:
+
+```bash
+npm pack
+```
+
+3. Publish:
+
+```bash
+npm publish
+```
+
+## Post-Publish Smoke Check
+
+Verify npm sees the release:
+
+```bash
+npm view @mthanhlm/autodev version
+```
+
+Then install from npm in a scratch directory:
+
+```bash
+mkdir -p /tmp/autodev-smoke
+cd /tmp/autodev-smoke
+npx @mthanhlm/autodev@latest --local
+```
+
+Open Claude Code in that directory and run:
+
+```text
+/autodev-help
+```

package/README.md

@@ -0,0 +1,53 @@
+# autodev
+
+`autodev` is a Claude Code workflow package built for one thing: get from idea to shipped code without the slow, over-engineered, git-writing behavior that made GSD painful.
+
+## What It Does
+
+- Installs a small Claude Code workflow under `~/.claude/` or `./.claude/`
+- Keeps project state in `.autodev/`
+- Ships six commands:
+  - `/autodev-help`
+  - `/autodev-new-project`
+  - `/autodev-plan-phase`
+  - `/autodev-execute-phase`
+  - `/autodev-verify-work`
+  - `/autodev-progress`
+- Treats git as read-only inside the workflow
+
+## Install
+
+```bash
+npx @mthanhlm/autodev@latest --global
+```
+
+Local install for one repo:
+
+```bash
+npx @mthanhlm/autodev@latest --local
+```
+
+Uninstall:
+
+```bash
+npx @mthanhlm/autodev@latest --global --uninstall
+npx @mthanhlm/autodev@latest --local --uninstall
+```
+
+## Default Flow
+
+```text
+/autodev-new-project
+/autodev-plan-phase 1
+/autodev-execute-phase 1
+/autodev-verify-work 1
+/autodev-progress
+```
+
+## Git Policy
+
+`autodev` does not stage, commit, branch, merge, worktree, pull, push, or initialize git repositories. Read-only git commands like `git status`, `git diff`, and `git log` remain allowed.
+
+## Publish
+
+Release steps are in [PUBLISH.md](PUBLISH.md).

package/autodev/bin/autodev-tools.cjs

@@ -0,0 +1,346 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_CONFIG = {
+  workflow: {
+    research: false
+  },
+  execution: {
+    parallel: false
+  },
+  git: {
+    mode: 'read-only'
+  },
+  hooks: {
+    context_warnings: true,
+    read_guard: true,
+    workflow_guard: true,
+    prompt_guard: true,
+    git_guard: true,
+    session_state: true,
+    phase_boundary: true
+  }
+};
+
+function autodevDir(cwd) {
+  return path.join(cwd, '.autodev');
+}
+
+function readText(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function readJson(filePath, fallback = null) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+function slugify(value) {
+  return String(value)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .replace(/-+/g, '-') || 'phase';
+}
+
+function padPhase(number) {
+  return String(number).padStart(2, '0');
+}
+
+function parseRoadmap(content) {
+  const phases = [];
+  if (!content) {
+    return phases;
+  }
+
+  const matcher = /^##\s+Phase\s+(\d+)\s*:\s*(.+)$/gm;
+  let match;
+  while ((match = matcher.exec(content)) !== null) {
+    phases.push({
+      number: Number(match[1]),
+      name: match[2].trim()
+    });
+  }
+  return phases;
+}
+
+function phasePaths(cwd, phase) {
+  const dirName = `${padPhase(phase.number)}-${slugify(phase.name)}`;
+  const dir = path.join(autodevDir(cwd), 'phases', dirName);
+  const prefix = padPhase(phase.number);
+  return {
+    ...phase,
+    padded: prefix,
+    dir,
+    planPath: path.join(dir, `${prefix}-PLAN.md`),
+    summaryPath: path.join(dir, `${prefix}-SUMMARY.md`),
+    uatPath: path.join(dir, `${prefix}-UAT.md`)
+  };
+}
+
+function loadConfig(cwd) {
+  const config = readJson(path.join(autodevDir(cwd), 'config.json'), {});
+  return {
+    workflow: {
+      ...DEFAULT_CONFIG.workflow,
+      ...(config.workflow || {})
+    },
+    execution: {
+      ...DEFAULT_CONFIG.execution,
+      ...(config.execution || {})
+    },
+    git: {
+      ...DEFAULT_CONFIG.git,
+      ...(config.git || {})
+    },
+    hooks: {
+      ...DEFAULT_CONFIG.hooks,
+      ...(config.hooks || {})
+    }
+  };
+}
+
+function listPhases(cwd) {
+  const roadmap = readText(path.join(autodevDir(cwd), 'ROADMAP.md'));
+  return parseRoadmap(roadmap).map(phase => {
+    const details = phasePaths(cwd, phase);
+    const planExists = fs.existsSync(details.planPath);
+    const summaryExists = fs.existsSync(details.summaryPath);
+    const uatExists = fs.existsSync(details.uatPath);
+    const status = uatExists
+      ? 'verified'
+      : summaryExists
+        ? 'executed'
+        : planExists
+          ? 'planned'
+          : 'pending';
+
+    return {
+      ...details,
+      planExists,
+      summaryExists,
+      uatExists,
+      status
+    };
+  });
+}
+
+function resolvePhase(cwd, requestedPhase, mode) {
+  const phases = listPhases(cwd);
+  if (phases.length === 0) {
+    return null;
+  }
+
+  if (requestedPhase) {
+    const numeric = Number(requestedPhase);
+    return phases.find(phase => phase.number === numeric) || null;
+  }
+
+  if (mode === 'plan') {
+    return phases.find(phase => !phase.planExists) || phases[0];
+  }
+
+  if (mode === 'execute') {
+    return phases.find(phase => phase.planExists && !phase.summaryExists) || null;
+  }
+
+  if (mode === 'verify') {
+    return phases.find(phase => phase.summaryExists && !phase.uatExists)
+      || [...phases].reverse().find(phase => phase.summaryExists)
+      || null;
+  }
+
+  return phases[0];
+}
+
+function nextCommand(progress) {
+  if (!progress.initialized) {
+    return '/autodev-new-project';
+  }
+
+  const nextVerify = progress.phases.find(phase => phase.summaryExists && !phase.uatExists);
+  if (nextVerify) {
+    return `/autodev-verify-work ${nextVerify.number}`;
+  }
+
+  const nextExecute = progress.phases.find(phase => phase.planExists && !phase.summaryExists);
+  if (nextExecute) {
+    return `/autodev-execute-phase ${nextExecute.number}`;
+  }
+
+  const nextPlan = progress.phases.find(phase => !phase.planExists);
+  if (nextPlan) {
+    return `/autodev-plan-phase ${nextPlan.number}`;
+  }
+
+  return '/autodev-progress';
+}
+
+function buildProgress(cwd) {
+  const root = autodevDir(cwd);
+  const initialized = fs.existsSync(root);
+  if (!initialized) {
+    return {
+      initialized: false,
+      phases: [],
+      counts: {
+        total: 0,
+        planned: 0,
+        executed: 0,
+        verified: 0
+      },
+      nextCommand: '/autodev-new-project'
+    };
+  }
+
+  const phases = listPhases(cwd);
+  return {
+    initialized: true,
+    phases,
+    counts: {
+      total: phases.length,
+      planned: phases.filter(phase => phase.planExists).length,
+      executed: phases.filter(phase => phase.summaryExists).length,
+      verified: phases.filter(phase => phase.uatExists).length
+    },
+    nextCommand: nextCommand({ initialized: true, phases })
+  };
+}
+
+function renderProgressTable(progress) {
+  if (!progress.initialized) {
+    return 'No .autodev project found.\nNext: /autodev-new-project';
+  }
+
+  const lines = [
+    'Autodev Progress',
+    '',
+    `Phases: ${progress.counts.total}`,
+    `Planned: ${progress.counts.planned}`,
+    `Executed: ${progress.counts.executed}`,
+    `Verified: ${progress.counts.verified}`,
+    `Next: ${progress.nextCommand}`,
+    '',
+    '| Phase | Name | Plan | Summary | UAT | Status |',
+    '| --- | --- | --- | --- | --- | --- |'
+  ];
+
+  for (const phase of progress.phases) {
+    lines.push(
+      `| ${phase.number} | ${phase.name} | ${phase.planExists ? 'yes' : 'no'} | ${phase.summaryExists ? 'yes' : 'no'} | ${phase.uatExists ? 'yes' : 'no'} | ${phase.status} |`
+    );
+  }
+
+  return lines.join('\n');
+}
+
+function dotGet(object, key) {
+  return key.split('.').reduce((current, part) => (
+    current && Object.prototype.hasOwnProperty.call(current, part) ? current[part] : undefined
+  ), object);
+}
+
+function initPayload(cwd, mode, requestedPhase) {
+  const root = autodevDir(cwd);
+  const config = loadConfig(cwd);
+  const phase = mode === 'new-project' ? null : resolvePhase(cwd, requestedPhase, mode);
+  return {
+    cwd,
+    autodev_exists: fs.existsSync(root),
+    config_path: path.join(root, 'config.json'),
+    project_path: path.join(root, 'PROJECT.md'),
+    requirements_path: path.join(root, 'REQUIREMENTS.md'),
+    roadmap_path: path.join(root, 'ROADMAP.md'),
+    state_path: path.join(root, 'STATE.md'),
+    research_enabled: config.workflow.research,
+    git_mode: config.git.mode,
+    phase_found: Boolean(phase),
+    phase_number: phase ? phase.number : null,
+    phase_name: phase ? phase.name : null,
+    phase_dir: phase ? phase.dir : null,
+    plan_path: phase ? phase.planPath : null,
+    summary_path: phase ? phase.summaryPath : null,
+    uat_path: phase ? phase.uatPath : null,
+    plan_exists: phase ? phase.planExists : false,
+    summary_exists: phase ? phase.summaryExists : false,
+    uat_exists: phase ? phase.uatExists : false
+  };
+}
+
+function printJson(value) {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const cwd = process.cwd();
+
+  if (args.length === 0) {
+    process.stderr.write('autodev-tools: command required\n');
+    process.exit(1);
+  }
+
+  const [command, ...rest] = args;
+
+  if (command === 'progress') {
+    const mode = rest[0] || 'table';
+    const progress = buildProgress(cwd);
+    if (mode === 'json') {
+      printJson(progress);
+      return;
+    }
+    process.stdout.write(`${renderProgressTable(progress)}\n`);
+    return;
+  }
+
+  if (command === 'config-get') {
+    const key = rest[0];
+    if (!key) {
+      process.stderr.write('autodev-tools: config key required\n');
+      process.exit(1);
+    }
+    const value = dotGet(loadConfig(cwd), key);
+    if (typeof value === 'object') {
+      printJson(value);
+    } else if (value !== undefined) {
+      process.stdout.write(`${String(value)}\n`);
+    }
+    return;
+  }
+
+  if (command === 'init') {
+    const mode = rest[0];
+    const phase = rest[1];
+    if (!mode) {
+      process.stderr.write('autodev-tools: init mode required\n');
+      process.exit(1);
+    }
+    printJson(initPayload(cwd, mode, phase));
+    return;
+  }
+
+  process.stderr.write(`autodev-tools: unknown command "${command}"\n`);
+  process.exit(1);
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  autodevDir,
+  buildProgress,
+  loadConfig,
+  parseRoadmap,
+  renderProgressTable,
+  resolvePhase
+};

package/autodev/templates/config.json

@@ -0,0 +1,20 @@
+{
+  "workflow": {
+    "research": false
+  },
+  "execution": {
+    "parallel": false
+  },
+  "git": {
+    "mode": "read-only"
+  },
+  "hooks": {
+    "context_warnings": true,
+    "read_guard": true,
+    "workflow_guard": true,
+    "prompt_guard": true,
+    "git_guard": true,
+    "session_state": true,
+    "phase_boundary": true
+  }
+}

package/autodev/templates/plan.md

@@ -0,0 +1,25 @@
+# Phase [N] Plan: [Name]
+
+## Goal
+[Phase goal]
+
+## Inputs
+- PROJECT.md
+- REQUIREMENTS.md
+- ROADMAP.md
+- Current codebase state
+
+## Steps
+1. [Concrete task]
+2. [Concrete task]
+
+## Files Likely To Change
+- [path]
+
+## Verification
+- [Command]
+- [Manual check]
+
+## Git Policy
+- Read-only only.
+- Allowed: `git status`, `git diff`, `git log`, `git show`, `git rev-parse`, `git ls-files`, `git branch --show-current`.

package/autodev/templates/project.md

@@ -0,0 +1,21 @@
+# Project
+
+## One-Line Summary
+[Describe the product in one sentence.]
+
+## Problem
+[What pain are you solving?]
+
+## Users
+[Who is this for?]
+
+## Success Criteria
+- [Primary outcome]
+- [Primary quality bar]
+
+## Constraints
+- [Technical constraints]
+- [Business or time constraints]
+
+## Non-Goals
+- [Out of scope]

package/autodev/templates/requirements.md

@@ -0,0 +1,12 @@
+# Requirements
+
+## Must Have
+1. REQ-01: [Requirement]
+   Acceptance:
+   - [Observable outcome]
+
+## Nice to Have
+1. NICE-01: [Optional enhancement]
+
+## Non-Goals
+- [Explicitly excluded work]

package/autodev/templates/roadmap.md

@@ -0,0 +1,17 @@
+# Roadmap
+
+## Phase 1: [Name]
+Status: pending
+Goal: [What this phase achieves]
+Deliverables:
+- [Deliverable]
+Risks:
+- [Risk]
+
+## Phase 2: [Name]
+Status: pending
+Goal: [What this phase achieves]
+Deliverables:
+- [Deliverable]
+Risks:
+- [Risk]

package/autodev/templates/state.md

@@ -0,0 +1,10 @@
+# State
+
+Current Phase: 1
+Current Step: planning
+Status: active
+Next Command: /autodev-plan-phase 1
+Last Updated: [ISO timestamp]
+
+## Notes
+- Project initialized.

package/autodev/templates/summary.md

@@ -0,0 +1,16 @@
+# Phase [N] Summary: [Name]
+
+## Completed
+- [What shipped]
+
+## Files Changed
+- [path]
+
+## Verification
+- [Command and result]
+
+## Remaining Risks
+- [Known gap]
+
+## Next Step
+- Run `/autodev-verify-work [N]`

package/autodev/templates/uat.md

@@ -0,0 +1,15 @@
+# Phase [N] UAT: [Name]
+
+Status: pending
+
+## Test Cases
+- [ ] [Behavior to verify]
+
+## Results
+- [Pass/fail notes]
+
+## Bugs Or Follow-Up
+- [Issue or none]
+
+## Recommended Next Step
+- [Next command]

package/autodev/workflows/execute-phase.md

@@ -0,0 +1,50 @@
+<purpose>
+Execute a phase plan sequentially, keep the edits pragmatic, and capture the real outcome in a summary.
+</purpose>
+
+<rules>
+- Never run git write commands.
+- Do not create commits, branches, merges, or worktrees.
+- Stay within the current phase. Do not silently expand scope.
+- Execute sequentially by default. Do not create parallel sub-work unless the user explicitly asks for it.
+</rules>
+
+<process>
+1. Run:
+
+```bash
+node "$HOME/.claude/autodev/bin/autodev-tools.cjs" init execute-phase "$ARGUMENTS"
+```
+
+2. If no phase is found or the plan file is missing, stop and direct the user to `/autodev-plan-phase`.
+
+3. Read:
+   - `.autodev/STATE.md`
+   - the target `NN-PLAN.md`
+   - the source files needed for the current phase
+
+4. Execute the plan directly in the repository. Use normal coding tools, tests, and read-only git inspection if useful.
+
+5. Keep a short running note of:
+   - files changed
+   - commands run
+   - tests passed or failed
+   - any scope adjustments the user explicitly approved
+
+6. Write or update `NN-SUMMARY.md` from the template with:
+   - completed work
+   - files changed
+   - verification results
+   - remaining risks
+   - next step
+
+7. Update `.autodev/STATE.md` so it points to:
+   - `Current Phase: N`
+   - `Current Step: executed`
+   - `Next Command: /autodev-verify-work N`
+   - current ISO timestamp
+
+8. If the phase is blocked or incomplete, say so clearly in the summary and set the next command back to `/autodev-execute-phase N`.
+
+9. End with a short outcome summary and the next recommended command.
+</process>