@mthanhlm/autodev 0.1.0 → 0.2.0

package/autodev/templates/codebase/runtime.md

@@ -0,0 +1,13 @@
+# 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

@@ -0,0 +1,13 @@
+# 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

@@ -0,0 +1,13 @@
+# 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,6 +1,11 @@
 {
+  "project": {
+    "type": null
+  },
   "workflow": {
-    "research": false
+    "research": false,
+    "review_after_execute": true,
+    "codebase_parallel_agents": 4
   },
   "execution": {
     "parallel": false

package/autodev/templates/plan.md

@@ -1,10 +1,14 @@
 # Phase [N] Plan: [Name]
 
+Type: [feature|bugfix|refactor|research|polish]
+
 ## Goal
 [Phase goal]
 
 ## Inputs
 - PROJECT.md
+- codebase summary if available
+- TRACK.md
 - REQUIREMENTS.md
 - ROADMAP.md
 - Current codebase state

package/autodev/templates/project-state.md

@@ -0,0 +1,11 @@
+# Project State
+
+Project Type: [greenfield or brownfield]
+Active Track: [slug]
+Current Step: initialized
+Status: active
+Next Command: /autodev
+Last Updated: [ISO timestamp]
+
+## Notes
+- Project initialized.

package/autodev/templates/project.md

@@ -3,6 +3,9 @@
 ## One-Line Summary
 [Describe the product in one sentence.]
 
+## Project Type
+[greenfield or brownfield]
+
 ## Problem
 [What pain are you solving?]
 

package/autodev/templates/requirements.md

@@ -1,5 +1,7 @@
 # Requirements
 
+Track: [Name]
+
 ## Must Have
 1. REQ-01: [Requirement]
    Acceptance:

package/autodev/templates/review.md

@@ -0,0 +1,24 @@
+# Phase [N] Review: [Name]
+
+Status: pending
+
+## Code Quality
+- [Finding or "no blocking findings"]
+
+## Security
+- [Finding or "no blocking findings"]
+
+## Integration And Regression
+- [Finding or "no blocking findings"]
+
+## Product Polish And AI-Look
+- [Finding or "no blocking findings"]
+
+## Blockers
+- [Blocker or "none"]
+
+## Strengths
+- [What looks solid]
+
+## Recommendation
+- [Return to execution or continue to verification]

package/autodev/templates/roadmap.md

@@ -1,6 +1,6 @@
-# Roadmap
+# Track Roadmap
 
-## Phase 1: [Name]
+## Phase 1 [feature]: [Name]
 Status: pending
 Goal: [What this phase achieves]
 Deliverables:
@@ -8,7 +8,7 @@ Deliverables:
 Risks:
 - [Risk]
 
-## Phase 2: [Name]
+## Phase 2 [feature]: [Name]
 Status: pending
 Goal: [What this phase achieves]
 Deliverables:

package/autodev/templates/state.md

@@ -1,9 +1,10 @@
-# State
+# Project State
 
-Current Phase: 1
-Current Step: planning
+Project Type: [greenfield or brownfield]
+Active Track: [slug]
+Current Step: initialized
 Status: active
-Next Command: /autodev-plan-phase 1
+Next Command: /autodev
 Last Updated: [ISO timestamp]
 
 ## Notes

package/autodev/templates/summary.md

@@ -1,5 +1,7 @@
 # Phase [N] Summary: [Name]
 
+Type: [feature|bugfix|refactor|research|polish]
+
 ## Completed
 - [What shipped]
 
@@ -13,4 +15,4 @@
 - [Known gap]
 
 ## Next Step
-- Run `/autodev-verify-work [N]`
+- Run `/autodev`

package/autodev/templates/track-state.md

@@ -0,0 +1,12 @@
+# Track State
+
+Track: [Name]
+Current Phase: 1
+Current Phase Type: [feature]
+Current Step: planning
+Status: active
+Next Command: /autodev
+Last Updated: [ISO timestamp]
+
+## Notes
+- Track ready.

package/autodev/templates/track.md

@@ -0,0 +1,17 @@
+# Track: [Name]
+
+Type: [feature|bugfix|refactor|research|polish]
+Status: active
+
+## Outcome
+[What this track is trying to achieve.]
+
+## Scope Boundaries
+- [What is in scope]
+- [What is explicitly out of scope]
+
+## Dependencies
+- [Team, system, or technical dependency]
+
+## Existing Code Notes
+- [Important brownfield context or leave none]

package/autodev/templates/uat.md

@@ -6,10 +6,13 @@ Status: pending
 - [ ] [Behavior to verify]
 
 ## Results
-- [Pass/fail notes]
+- [Pass or fail notes]
 
 ## Bugs Or Follow-Up
 - [Issue or none]
 
+## Fix Return
+- [Only add when verification fails]
+
 ## Recommended Next Step
-- [Next command]
+- `/autodev`

package/autodev/workflows/autodev.md

@@ -0,0 +1,62 @@
+<purpose>
+Use `/autodev` as the single entrypoint for the normal workflow. Route automatically, keep git read-only, and move the project forward in the same turn whenever possible.
+</purpose>
+
+<rules>
+- Prefer `/autodev` over telling the user to run a different command manually.
+- Manual commands remain valid escape hatches. Mention them only as shortcuts.
+- Keep the model `project -> track -> phase`.
+- Brownfield repositories should be mapped before detailed phase planning.
+- Never run git write commands.
+</rules>
+
+<process>
+1. Run:
+
+```bash
+node "$HOME/.claude/autodev/bin/autodev-tools.cjs" init autodev
+```
+
+2. Inspect the returned `route.kind`, `project_type`, `tracks`, and active phase 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.
+   - `review_phase`: perform the review-phase workflow.
+   - `verify_phase`: perform the verify-work workflow.
+
+4. 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:
+     - `.autodev/ACTIVE_TRACK`
+     - `.autodev/tracks/<slug>/TRACK.md`
+     - `.autodev/tracks/<slug>/REQUIREMENTS.md`
+     - `.autodev/tracks/<slug>/ROADMAP.md`
+     - `.autodev/tracks/<slug>/STATE.md`
+   - Use a lowercase hyphenated slug.
+   - Use roadmap headings in this format:
+
+```text
+## Phase N [type]: Name
+```
+
+   - After track setup, continue in the same turn by re-running the route logic mentally and executing the next step.
+
+5. If the route is `track_complete`, ask whether the user wants to:
+   - start a new track
+   - run cleanup
+   - stop here
+
+6. When the user chooses a new track at step 5, create it immediately and continue routing in the same turn.
+
+7. Every time you finish a routed step, keep both project-level and track-level state aligned. Default the state files to `Next Command: /autodev`.
+
+8. End with:
+   - what step you completed
+   - the current route reason in plain language
+   - `/autodev` as the default next command
+   - the matching manual shortcut when useful
+</process>

package/autodev/workflows/cleanup.md

@@ -0,0 +1,45 @@
+<purpose>
+Clean or archive autodev state without flags. Prefer preserving useful project context over deleting it.
+</purpose>
+
+<rules>
+- Ask the user which cleanup action to take. Do not rely on flags.
+- Archive before delete when a safe archive path makes sense.
+- Require typed confirmation before deleting all `.autodev/` state.
+- Never touch repository code outside `.autodev/`.
+</rules>
+
+<process>
+1. Run:
+
+```bash
+node "$HOME/.claude/autodev/bin/autodev-tools.cjs" init autodev
+```
+
+2. If no `.autodev/` project exists, stop and say there is nothing to clean.
+
+3. Ask the user to choose one action:
+   - archive completed phase artifacts only
+   - archive the current track and clear the active selection
+   - delete all `.autodev/` state
+
+4. For `archive completed phase artifacts only`:
+   - create `.autodev/archive/<track-slug>/phases/` if needed
+   - move only verified phase directories there
+   - leave project docs, codebase docs, active track, and unfinished phases in place
+   - update project and track state to `Next Command: /autodev`
+
+5. For `archive the current track and clear the active selection`:
+   - move `.autodev/tracks/<slug>/` to `.autodev/archive/tracks/<slug>-<timestamp>/`
+   - remove `.autodev/ACTIVE_TRACK`
+   - update `.autodev/STATE.md` to `Current Step: track-selection` and `Next Command: /autodev`
+
+6. For `delete all .autodev state`:
+   - ask the user to type `DELETE AUTODEV`
+   - only then remove `.autodev/`
+
+7. End with:
+   - what was archived or deleted
+   - what project context remains
+   - the next recommended route
+</process>

package/autodev/workflows/execute-phase.md

@@ -1,5 +1,5 @@
 <purpose>
-Execute a phase plan sequentially, keep the edits pragmatic, and capture the real outcome in a summary.
+Execute an active-track phase plan sequentially, keep the edits pragmatic, and capture the real outcome in a summary.
 </purpose>
 
 <rules>
@@ -20,6 +20,8 @@ node "$HOME/.claude/autodev/bin/autodev-tools.cjs" init execute-phase "$ARGUMENT
 
 3. Read:
    - `.autodev/STATE.md`
+   - `.autodev/tracks/<active-track>/STATE.md`
+   - `.autodev/codebase/summary.md` if it exists
    - the target `NN-PLAN.md`
    - the source files needed for the current phase
 
@@ -38,13 +40,20 @@ node "$HOME/.claude/autodev/bin/autodev-tools.cjs" init execute-phase "$ARGUMENT
    - remaining risks
    - next step
 
-7. Update `.autodev/STATE.md` so it points to:
+7. Update the active track `STATE.md` so it points to:
    - `Current Phase: N`
-   - `Current Step: executed`
-   - `Next Command: /autodev-verify-work N`
+   - `Current Phase Type: <type>`
+   - `Current Step: review`
+   - `Next Command: /autodev`
    - 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`.
+8. Update `.autodev/STATE.md` so it points to:
+   - `Active Track: <slug>`
+   - `Current Step: review`
+   - `Next Command: /autodev`
+   - current ISO timestamp
+
+9. If the phase is blocked or incomplete, say so clearly in the summary and set both state files back to `Current Step: execution`, with `Next Command: /autodev`.
 
-9. End with a short outcome summary and the next recommended command.
+10. End with a short outcome summary and the next recommended command. Mention that the automatic review bundle is the next routed step.
 </process>

package/autodev/workflows/explore-codebase.md

@@ -0,0 +1,57 @@
+<purpose>
+Map a brownfield repository quickly and use four parallel agents to produce a usable codebase brief without drifting into over-analysis.
+</purpose>
+
+<rules>
+- Always spawn four agents in parallel for this workflow.
+- 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.
+</rules>
+
+<process>
+1. Run:
+
+```bash
+node "$HOME/.claude/autodev/bin/autodev-tools.cjs" init explore-codebase
+```
+
+2. If no project exists, stop and tell the user to use `/autodev` or `/autodev-new-project`.
+
+3. Read:
+   - `.autodev/PROJECT.md`
+   - `.autodev/STATE.md`
+   - `.autodev/ACTIVE_TRACK`
+   - the active track docs if they exist
+   - representative repo files needed to orient the exploration
+
+4. 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`
+   - `autodev-codebase-quality` owns `.autodev/codebase/quality.md`
+
+5. 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. After the four agent outputs are written, 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:
+   - `Current Step: planning`
+   - `Next Command: /autodev`
+   - refreshed ISO timestamp
+
+8. End with:
+   - the biggest structural insight
+   - the biggest risk
+   - `/autodev` as the next command
+   - `/autodev-plan-phase <n>` as the manual shortcut when obvious
+</process>

package/autodev/workflows/help.md

@@ -2,29 +2,62 @@
 
 Lean Claude Code workflow. No automatic commits. No branches. No worktrees. Git is read-only.
 
-## Commands
+## Main Entry
 
+- `/autodev`
+  The normal command. It routes automatically through project setup, codebase mapping, planning, execution, review, verification, and cleanup.
+
+## Manual Commands
+
+- `/autodev-help`
+  Shows this reference.
 - `/autodev-new-project`
-  Creates `.autodev/PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md`, and `config.json`.
+  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/`.
 - `/autodev-plan-phase [phase]`
-  Creates or revises one phase plan in `.autodev/phases/NN-name/NN-PLAN.md`.
+  Creates or revises one phase plan in `.autodev/tracks/<track>/phases/NN-type-name/NN-PLAN.md`.
 - `/autodev-execute-phase [phase]`
   Executes one phase plan sequentially and writes `NN-SUMMARY.md`.
+- `/autodev-review-phase [phase]`
+  Spawns four review agents for code quality, security, integration, and polish, then writes `NN-REVIEW.md`.
 - `/autodev-verify-work [phase]`
-  Records manual verification in `NN-UAT.md`.
+  Records manual verification in `NN-UAT.md` and captures fix-return gaps when verification fails.
 - `/autodev-progress`
-  Shows the current project status and next command.
-- `/autodev-help`
-  Shows this reference.
+  Shows project type, active track, phase status, and the next recommended route.
+- `/autodev-cleanup`
+  Asks what to clean or archive. No flags required.
+
+## Workflow Model
+
+```text
+project -> track -> phase
+```
+
+- `project`
+  Whole repo or product context.
+- `track`
+  The current initiative, feature line, refactor, or bugfix stream.
+- `phase`
+  Small execution slices inside the active track.
 
 ## Default Flow
 
 ```text
-/autodev-new-project
-/autodev-plan-phase 1
-/autodev-execute-phase 1
-/autodev-verify-work 1
-/autodev-progress
+/autodev
+```
+
+Typical brownfield route:
+
+```text
+/autodev
+  -> new project
+  -> explore codebase
+  -> plan
+  -> execute
+  -> review
+  -> verify
+  -> next track or cleanup
 ```
 
 ## Git Policy

package/autodev/workflows/new-project.md

@@ -1,11 +1,12 @@
 <purpose>
-Initialize `.autodev/` with the minimum useful project context. Prefer fast clarity over exhaustive ceremonies.
+Initialize `.autodev/` with useful project-level context, then create the first active track. Prefer fast clarity over exhaustive ceremonies.
 </purpose>
 
 <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.
+- Treat the repository as a `project`, then put the current initiative in a `track`.
 </rules>
 
 <process>
@@ -15,34 +16,57 @@ Initialize `.autodev/` with the minimum useful project context. Prefer fast clar
 node "$HOME/.claude/autodev/bin/autodev-tools.cjs" init new-project
 ```
 
-2. If `.autodev/PROJECT.md` already exists, stop and tell the user to use `/autodev-progress`.
+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 to write a real roadmap, ask a short set of questions to lock:
-   - the product outcome
-   - the primary user
-   - any hard constraints
+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
 
 4. Read the templates from the execution context.
 
 5. Create `.autodev/config.json` from the template with these defaults unless the user explicitly asks otherwise:
+   - `project.type: "greenfield"` or `"brownfield"`
    - `workflow.research: false`
+   - `workflow.review_after_execute: true`
+   - `workflow.codebase_parallel_agents: 4`
    - `execution.parallel: false`
    - `git.mode: "read-only"`
 
 6. Write `.autodev/PROJECT.md` with:
    - one-line summary
-   - problem
-   - users
+   - project type
+   - repo or product problem
+   - users or operators
    - success criteria
    - constraints
    - non-goals
 
-7. Write `.autodev/REQUIREMENTS.md` with clear must-have requirements and acceptance bullets.
+7. Create `.autodev/ACTIVE_TRACK` with a lowercase hyphenated slug for the first track.
 
-8. Write `.autodev/ROADMAP.md` with 3-8 phases using this exact heading format:
+8. Write `.autodev/STATE.md` with:
+   - `Project Type: ...`
+   - `Active Track: <slug>`
+   - `Current Step: initialized`
+   - `Status: active`
+   - `Next Command: /autodev`
+   - current ISO timestamp
+
+9. Create `.autodev/tracks/<slug>/TRACK.md` with:
+   - track name
+   - type or workstream shape
+   - desired outcome
+   - scope boundaries
+   - 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.
+
+11. Write `.autodev/tracks/<slug>/ROADMAP.md` with 2-8 phases using this exact heading format:
 
 ```text
-## Phase N: Name
+## Phase N [type]: Name
 ```
 
 Each phase must include:
@@ -51,12 +75,15 @@ Each phase must include:
    - `Deliverables:`
    - `Risks:`
 
-9. Write `.autodev/STATE.md` with:
+12. Write `.autodev/tracks/<slug>/STATE.md` with:
    - `Current Phase: 1`
+   - `Current Phase Type: <type>`
    - `Current Step: planning`
    - `Status: active`
-   - `Next Command: /autodev-plan-phase 1`
+   - `Next Command: /autodev`
    - current ISO timestamp
 
-10. End with a short summary and direct the user to `/autodev-plan-phase 1`.
+13. If the project is brownfield, do not fake a codebase map. Leave that for `/autodev-explore-codebase`, and make that the default next step. Otherwise, the next step is planning phase 1.
+
+14. End with a short summary and direct the user to `/autodev`. Mention the manual shortcut only if useful.
 </process>