multi-agents-cli 1.0.35 → 1.0.37

package/README.md

@@ -1,6 +1,10 @@
 # Multi Agents
 
-Multi-agent workflow orchestration for Claude Code — isolated git worktrees, structured state tracking, autonomous task chaining.
+A structured workflow tool that orchestrates multiple Claude Code agents working in parallel - each isolated in its own git worktree, owning a specific scope of the codebase.
+
+Instead of one agent doing everything in a single bloated session, each agent stays focused, token-efficient, and conflict-free. Shared state files keep them coordinated without manual intervention.
+
+**The result:** faster builds, lower token spend, and a clean git history - without sacrificing reliability or context.
 
 ---
 
@@ -31,29 +35,39 @@ npm run agent
 
 ---
 
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `npm run init` | Re-run initialization or restart a process |
+| `npm run agent` | Start a new task with an agent |
+| `npm run complete` | Agent finished - merge and move on |
+
+All three commands self-relocate to the repo root via `git rev-parse --git-common-dir`. Run them from the worktree terminal, the repo root, or anywhere inside the git tree.
+
+---
+
 ## Workflow
 
-### 1. Launch a task
+### 1. Start a task
 
 ```bash
 npm run agent
 ```
 
-Select scope → agent → describe the task (or press Enter for default) →
-workspace opens in your IDE automatically.
+Select scope (client/backend/shared) then agent then describe the task.
+The workspace opens in your IDE automatically.
 
 The agent reads `TASK.md` and executes autonomously.
 
 ### 2. Agent completes the task
 
 The agent commits its work and runs `npm run complete` autonomously.
-This merges the branch into main, updates `BUILD_STATE.md`, and clears
-the tracking slot.
+This merges the branch into main, updates `BUILD_STATE.md`, and clears the tracking slot.
 
 ### 3. Repeat
 
-`npm run complete` chains back to `npm run agent`. Pick the next agent
-and continue building.
+`npm run complete` chains back to `npm run agent`. Pick the next agent and continue building.
 
 ---
 
@@ -62,31 +76,24 @@ and continue building.
 Choose during `multi-agents init`:
 
 **Multi-Agent Driven Orchestration** *(recommended)*
-Every task should start with `npm run agent`. Each agent works in its own
-git worktree — an isolated branch and folder that merges back into main via
-`npm run complete`. Faster builds and lower token spend than a single long session.
-⚠ If you commit directly to main yourself, you bypass the framework and break
-task tracking for any active agent branches.
+Every task starts with `npm run agent`. Each agent works in its own git worktree - an isolated branch and folder that merges back into main via `npm run complete`. Faster builds and lower token spend than a single long session.
+If you commit directly to main yourself, you bypass the framework and break task tracking for any active agent branches.
 
 **Shared Orchestration**
-You and agents co-build — each owning a defined part of the codebase. Agent
-tasks run in git worktrees; your work happens directly in the project. Define
-boundaries before work begins.
-⚠ If you and an agent touch the same file, expect merge conflicts.
+You and agents co-build - each owning a defined part of the codebase. Agent tasks run in git worktrees; your work happens directly in the project. Define boundaries before work begins.
+If you and an agent touch the same file, expect merge conflicts.
 
 ---
 
 ## Supported Frameworks
 
 ### Client
-Next.js · Angular · Vue/Nuxt · SvelteKit · Vite+React · Remix
+Next.js - Angular - Vue/Nuxt - SvelteKit - Vite+React - Remix
 
 ### Backend (separate)
-Express · NestJS · Fastify · FastAPI · Django
+Express - NestJS - Fastify - FastAPI - Django
 
-Each framework has a dedicated scaffold instruction file in
-`client/frameworks/` and `backend/frameworks/` — agents read these
-before scaffolding to ensure files land in the correct location.
+Each framework has a dedicated scaffold instruction file in `.frameworks/client/` and `.frameworks/backend/` - agents read these before scaffolding to ensure files land in the correct location.
 
 ---
 
@@ -96,24 +103,24 @@ before scaffolding to ensure files land in the correct location.
 
 | Agent | Default task | Requires |
 |-------|-------------|---------|
-| `UI` | Scaffolds full project structure | — |
-| `LOGIC` | State management, API integration, hooks | UI ✓ |
-| `FORMS` | Form components, validation, submission | UI ✓ |
-| `ROUTING` | Page routing, navigation, URL structure | UI ✓ |
-| `TESTING` | Unit and integration tests | UI ✓ |
-| `ACCESSIBILITY` | a11y compliance, keyboard navigation | UI ✓ |
+| `UI` | Scaffolds full project structure | - |
+| `LOGIC` | State management, API integration, hooks | UI done |
+| `FORMS` | Form components, validation, submission | UI done |
+| `ROUTING` | Page routing, navigation, URL structure | UI done |
+| `TESTING` | Unit and integration tests | UI done |
+| `ACCESSIBILITY` | a11y compliance, keyboard navigation | UI done |
 
 ### Backend (separate only)
 
 | Agent | Default task | Requires |
 |-------|-------------|---------|
-| `API` | REST/GraphQL endpoints — start here | — |
-| `LOGIC` | Business logic, services, data processing | API ✓ |
-| `AUTH` | Authentication, authorization, sessions | API ✓ |
-| `DB` | Database schemas, migrations, queries | — |
-| `EVENTS` | Event queues, pub/sub, webhooks | API ✓ |
-| `JOBS` | Background jobs, scheduled tasks | API ✓ |
-| `TESTING` | API and integration tests | API ✓ |
+| `API` | REST/GraphQL endpoints - start here | - |
+| `LOGIC` | Business logic, services, data processing | API done |
+| `AUTH` | Authentication, authorization, sessions | API done |
+| `DB` | Database schemas, migrations, queries | - |
+| `EVENTS` | Event queues, pub/sub, webhooks | API done |
+| `JOBS` | Background jobs, scheduled tasks | API done |
+| `TESTING` | API and integration tests | API done |
 
 ### Shared
 
@@ -121,8 +128,7 @@ before scaffolding to ensure files land in the correct location.
 |-------|-------------|
 | `SECURITY` | Shared auth utilities, encryption, validation |
 
-> **Start with UI (client) or API (backend).** The launcher recommends
-> the correct next agent dynamically based on what's already completed.
+Start with UI (client) or API (backend). The launcher recommends the correct next agent dynamically based on what is already completed.
 
 ---
 
@@ -136,20 +142,18 @@ npm install
 npm run dev
 ```
 
-For deployment (Vercel, Netlify etc.) set the **root directory** to
-`client/` — not the repo root.
+For deployment set the root directory to `client/` - not the repo root.
 
 ---
 
 ## Remote Setup
 
-`multi-agents init` does NOT configure a GitHub remote. Your first agent
-session handles remote setup automatically:
+`multi-agents init` does not configure a GitHub remote. The first agent session handles remote setup automatically:
 
 1. Checks SSH, gh CLI, and HTTPS credentials in order
-2. If a remote repo exists — evaluates its state (orphaned branches, completion status, age)
+2. If a remote repo exists - evaluates its state (orphaned branches, completion status, age)
 3. Auto-clears old sessions or surfaces a decision when unfinished work is detected
-4. If no remote — opens your browser to `github.com/new` with the repo name pre-filled
+4. If no remote - opens your browser to `github.com/new` with the repo name pre-filled
 
 No manual `git remote add` needed.
 
@@ -159,16 +163,15 @@ No manual `git remote add` needed.
 
 | File | Purpose |
 |------|---------|
-| `CLAUDE.md` | Global coordination rules — every agent reads this first |
-| `BUILD_STATE.md` | Living project state — what's built, what's next |
-| `CONTRACTS.md` | Shared types and interfaces — single source of truth |
-| `TASK.md` | Per-task instructions — lives in the agent's worktree |
+| `CLAUDE.md` | Global coordination rules - every agent reads this first |
+| `BUILD_STATE.md` | Living project state - what is built, what is next |
+| `CONTRACTS.md` | Shared types and interfaces - single source of truth |
+| `TASK.md` | Per-task instructions - lives in the agent worktree |
 | `.scaffold/.config.json` | Project config written at init time |
-| `.scaffold/.tracking.json` | Active agent state — managed by workflow scripts |
-| `.scaffold/.paths.json` | Expected and actual framework paths — updated by agents after scaffolding |
+| `.scaffold/.tracking.json` | Active agent state - managed by workflow scripts |
+| `.scaffold/.paths.json` | Expected and actual framework paths - updated by agents after scaffolding |
 
-> **Never edit `BUILD_STATE.md` directly.** `npm run complete` owns all
-> updates to it. Editing it in a worktree causes merge conflicts.
+Never edit `BUILD_STATE.md` directly. `npm run complete` owns all updates to it. Editing it in a worktree causes merge conflicts.
 
 ---
 
@@ -177,19 +180,18 @@ No manual `git remote add` needed.
 Context loads in this order for every agent:
 
 ```
-Root CLAUDE.md             ← global rules, protocols, tracking schema
-        ↓
-client/CLAUDE.md           ← stack config, framework scaffold instructions
-        ↓
-client/frameworks/{fw}.md  ← exact scaffold commands and path conventions
-        ↓
-agents/UI.md               ← agent-specific behavior and constraints
-        ↓
-TASK.md                    ← the specific task to execute
+Root CLAUDE.md                     <- global rules, protocols, tracking schema
+        |
+client/CLAUDE.md                   <- stack config, framework scaffold instructions
+        |
+.frameworks/client/{fw}.md         <- exact scaffold commands and path conventions
+        |
+.agents/client/UI.md               <- agent-specific behavior and constraints
+        |
+TASK.md                            <- the specific task to execute
 ```
 
-Each layer narrows scope. Agents never need to be told what framework
-or language to use — it's resolved from config automatically.
+Each layer narrows scope. Agents never need to be told what framework or language to use - it is resolved from config automatically.
 
 ---
 
@@ -197,11 +199,11 @@ or language to use — it's resolved from config automatically.
 
 The launcher enforces structural rules before any worktree is created:
 
-- **Skeleton guard** — LOGIC/FORMS/ROUTING/TESTING require UI completed first
-- **Prerequisite check** — surfaces unmet dependencies, lets you proceed or repick
-- **Active agent gate** — if the same agent is already running, offers Continue / Complete / Abandon / Pick again
-- **MISSING gate** — if a worktree was deleted without completing, mandatory Recover or Reset decision
-- **Coexistence check** — if recovering, surfaces file conflicts and divergence before restoring
+- **Skeleton guard** - LOGIC/FORMS/ROUTING/TESTING require UI completed first
+- **Prerequisite check** - surfaces unmet dependencies, lets you proceed or repick
+- **Active agent gate** - if the same agent is already running, offers Continue / Complete / Abandon / Pick again
+- **MISSING gate** - if a worktree was deleted without completing, mandatory Recover or Reset decision
+- **Coexistence check** - if recovering, surfaces file conflicts and divergence before restoring
 
 ---
 
@@ -223,7 +225,7 @@ The launcher enforces structural rules before any worktree is created:
 }
 ```
 
-**Status values:** `null` (never launched) · `ACTIVE` (running) · `MISSING` (worktree deleted without completing)
+**Status values:** `null` (never launched) - `ACTIVE` (running) - `MISSING` (worktree deleted without completing)
 
 Managed entirely by `agent.js` and `complete.js`. Never edit manually.
 
@@ -245,46 +247,33 @@ Managed entirely by `agent.js` and `complete.js`. Never edit manually.
 }
 ```
 
-**Status values:** `pending` (not yet scaffolded) · `verified` (agent confirmed path) · `diverged` (actual path differs from expected)
+**Status values:** `pending` (not yet scaffolded) - `verified` (agent confirmed path) - `diverged` (actual path differs from expected)
 
 Written at init time. Updated by agents after scaffolding their framework.
 
 ---
 
-## Running Commands From Anywhere
-
-`npm run agent` and `npm run complete` self-relocate to the repo root
-via `git rev-parse --git-common-dir`. Run them from the worktree terminal,
-the repo root, or anywhere inside the git tree — they always work.
-
----
-
 ## Architecture
 
 ```
 my-project/
-├── client/                    ← built by client agents, merges into main
-│   ├── frameworks/            ← scaffold instruction files per framework
-│   └── src/
-├── backend/                   ← built by backend agents (if separate)
-│   └── frameworks/            ← scaffold instruction files per framework
+├── .agents/                        <- agent instruction files
+│   ├── client/                     <- UI.md, LOGIC.md, FORMS.md ...
+│   ├── backend/                    <- API.md, DB.md, AUTH.md ...
+│   └── shared/                     <- SECURITY.md
+├── .frameworks/                    <- framework scaffold instructions
+│   ├── client/                     <- nextjs.md, angular.md ...
+│   └── backend/                    <- express.md, fastapi.md ...
+├── .workflow/                      <- workflow scripts (agent.js, complete.js, guards.js)
+├── .scaffold/                      <- runtime state (config, tracking, paths, lock)
+├── client/                         <- built by client agents
+├── backend/                        <- built by backend agents (if separate)
 ├── shared/
-├── worktrees/                 ← local only, gitignored
-│   └── client-my-project-ui-1780403456467/
+├── worktrees/                      <- local only, gitignored
 ├── CLAUDE.md
 ├── BUILD_STATE.md
-├── CONTRACTS.md
-├── .scaffold/
-│   ├── .config.json
-│   ├── .tracking.json
-│   ├── .paths.json
-│   └── .initialized
-└── .workflow/
-    ├── agent.js
-    ├── complete.js
-    └── guards.js
+└── CONTRACTS.md
 ```
 
 Each agent works in its own `worktrees/` folder on a dedicated branch.
-On completion, its work merges into `main`. The final `main` branch is
-a complete, runnable application.
+On completion, its work merges into `main`. The final `main` branch is a complete, runnable application.

package/init.js

@@ -683,8 +683,8 @@ const main = async () => {
       }
 
       if (active.length === 0) {
-        console.log(yellow('\n  No active processes found.\n'));
-        return false;
+        console.log(yellow('\n  No active processes found. Nothing to restart.\n'));
+        return 'empty';
       }
 
       separator();
@@ -702,7 +702,7 @@ const main = async () => {
         ],
       }, { onCancel: () => process.exit(0) });
 
-      if (!pickRes.value || pickRes.value === '__back__') return false;
+      if (!pickRes.value || pickRes.value === '__back__') return 'back';
       const idx = active.findIndex(a => a.agent === pickRes.value);
       if (idx < 0) return false;
       const { scope, agent, data } = active[idx];
@@ -748,7 +748,7 @@ const main = async () => {
 
       if (confirmRes.value !== 'y') {
         console.log(dim('\n  Cancelled.\n'));
-        return false;
+        return 'back';
       }
 
       // Perform wipe
@@ -765,7 +765,7 @@ const main = async () => {
 
       fs.writeFileSync(trackingPath, JSON.stringify(tracking, null, 2), 'utf8');
       console.log(`\n  ${green('✓')} Restart complete.\n`);
-      return true;
+      return 'done';
     };
 
     if (prompts && process.stdin.isTTY) {
@@ -791,8 +791,8 @@ const main = async () => {
           child.on('exit', (code) => process.exit(code));
           return;
         } else if (res.value === '2') {
-          const didRestart = await showRestartProcess();
-          if (!didRestart) continue; // Back — show menu again
+          const restartResult = await showRestartProcess();
+          if (restartResult === 'back') continue; // Back — show menu again
           lockLoop = false;
           return;
         } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "multi-agents-cli",
-  "version": "1.0.35",
+  "version": "1.0.37",
   "description": "Multi-agent workflow orchestration for Claude Code — isolated git worktrees, structured state tracking, autonomous task chaining",
   "keywords": [
     "claude-code",