multi-agents-cli 1.0.7 → 1.0.9

package/README.md

@@ -1,39 +1,33 @@
-# Multi-Agent Monorepo Template
+# Multi Agents
 
-A scaffolding framework for building full-stack applications using multiple
-Claude Code agents working simultaneously in isolated git worktrees — each
-agent owning a specific domain, all coordinating through shared state.
+Multi-agent workflow orchestration for Claude Code — isolated git worktrees, structured state tracking, autonomous task chaining.
 
 ---
 
-## How It Works
-
-Three commands drive the entire workflow:
+## Install
 
 ```bash
-npm run init      # one-time project setup
-npm run launch    # create a new agent workspace
-npm run complete  # merge finished work, start next task
+npm install -g multi-agents-cli
 ```
 
-No manual worktree management. No manual branch creation. No repeated context.
-
 ---
 
 ## Quickstart
 
 ```bash
-git clone https://github.com/JDev-il/multi-agents-template.git my-project
+multi-agents init my-project
 cd my-project
-npm run init
+npm run launch
 ```
 
-`npm run init` will:
-- Ask for your project name, stack, and IDE preference
+`multi-agents init` will:
+- Guide you through project name, stack, IDE, and build trajectory using arrow-key selection
 - Fetch all templates and workflow scripts from multi-agents-core
 - Generate `BUILD_STATE.md`, `CONTRACTS.md`, `CLAUDE.md`
+- Generate `.scaffold/.paths.json` with expected framework paths
 - Initialize agent tracking (`.scaffold/.tracking.json`)
-- Set up git remote handling (see [Remote Setup](#remote-setup))
+- Install `prompts` dependency for arrow-key navigation
+- Set up git remote handling (first agent session handles this automatically)
 
 ---
 
@@ -63,6 +57,39 @@ and continue building.
 
 ---
 
+## Build Trajectories
+
+Choose during `multi-agents init`:
+
+**Multi-Agent Driven Orchestration** *(recommended)*
+Every task should start with `npm run launch`. 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.
+
+---
+
+## Supported Frameworks
+
+### Client
+Next.js · Angular · Vue/Nuxt · SvelteKit · Vite+React · Remix
+
+### Backend (separate)
+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.
+
+---
+
 ## Agent Roster
 
 ### Client
@@ -101,8 +128,7 @@ and continue building.
 
 ## Running the App
 
-After agents complete their tasks and merge into main, the app lives
-in `client/` (and `backend/` if configured separately):
+After agents complete their tasks and merge into main:
 
 ```bash
 cd client
@@ -117,15 +143,13 @@ For deployment (Vercel, Netlify etc.) set the **root directory** to
 
 ## Remote Setup
 
-`npm run init` does NOT configure a GitHub remote. It removes the template
-origin and leaves your project local-only.
-
-**Your first agent session handles remote setup automatically:**
+`multi-agents init` does NOT configure a GitHub remote. Your first agent
+session handles remote setup automatically:
 
 1. Checks SSH, gh CLI, and HTTPS credentials in order
-2. If a remote is reachable — uses it
-3. If not — opens your browser to `github.com/new` with the repo name
-   pre-filled, waits for you to create it, then wires everything up
+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
 
 No manual `git remote add` needed.
 
@@ -141,6 +165,7 @@ No manual `git remote add` needed.
 | `TASK.md` | Per-task instructions — lives in the agent's 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 |
 
 > **Never edit `BUILD_STATE.md` directly.** `npm run complete` owns all
 > updates to it. Editing it in a worktree causes merge conflicts.
@@ -152,13 +177,15 @@ No manual `git remote add` needed.
 Context loads in this order for every agent:
 
 ```
-Root CLAUDE.md          ← global rules, protocols, tracking schema
+Root CLAUDE.md             ← global rules, protocols, tracking schema
+        ↓
+client/CLAUDE.md           ← stack config, framework scaffold instructions
         ↓
-client/CLAUDE.md        ← stack config, client-specific rules
+client/frameworks/{fw}.md  ← exact scaffold commands and path conventions
         ↓
-agents/UI.md            ← agent-specific behavior and constraints
+agents/UI.md               ← agent-specific behavior and constraints
         ↓
-TASK.md                 ← the specific task to execute
+TASK.md                    ← the specific task to execute
 ```
 
 Each layer narrows scope. Agents never need to be told what framework
@@ -180,8 +207,7 @@ The launcher enforces structural rules before any worktree is created:
 
 ## Tracking
 
-`.scaffold/.tracking.json` is the runtime state ledger. Every agent slot
-is pre-defined at init time:
+`.scaffold/.tracking.json` is the runtime state ledger:
 
 ```json
 {
@@ -203,29 +229,33 @@ Managed entirely by `launch.js` and `complete.js`. Never edit manually.
 
 ---
 
-## Running Commands From Anywhere
+## Path Tracking
 
-`npm run launch` 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.
+`.scaffold/.paths.json` maps expected and actual framework paths:
 
----
+```json
+{
+  "client": {
+    "typesDir": {
+      "expected": "client/src/types",
+      "current": null,
+      "status": "pending"
+    }
+  }
+}
+```
 
-## Cloning vs Use as Template
+**Status values:** `pending` (not yet scaffolded) · `verified` (agent confirmed path) · `diverged` (actual path differs from expected)
 
-Both entry points work:
+Written at init time. Updated by agents after scaffolding their framework.
 
-**`git clone`** (quickstart, no GitHub account needed upfront)
-```bash
-git clone https://github.com/JDev-il/multi-agents-template.git my-project
-cd my-project
-npm run init
-```
-The template remote is automatically removed. Remote setup happens on first agent session.
+---
 
-**Use as Template** (recommended for production projects)
-Click "Use this template" on GitHub to create a repo under your own account
-with a clean history. Then clone your new repo and run `npm run init`.
+## Running Commands From Anywhere
+
+`npm run launch` 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.
 
 ---
 
@@ -233,19 +263,21 @@ with a clean history. Then clone your new repo and run `npm run init`.
 
 ```
 my-project/
-├── client/               ← built by client agents, merges into main
-│   ├── package.json
+├── client/                    ← built by client agents, merges into main
+│   ├── frameworks/            ← scaffold instruction files per framework
 │   └── src/
-├── backend/              ← built by backend agents (if separate)
-├── shared/               ← shared agent files
-├── worktrees/            ← local only, gitignored
-│   └── client-my-project-ui-1780403456467/   ← isolated agent workspace
+├── backend/                   ← built by backend agents (if separate)
+│   └── frameworks/            ← scaffold instruction files per framework
+├── shared/
+├── worktrees/                 ← local only, gitignored
+│   └── client-my-project-ui-1780403456467/
 ├── CLAUDE.md
 ├── BUILD_STATE.md
 ├── CONTRACTS.md
 ├── .scaffold/
 │   ├── .config.json
 │   ├── .tracking.json
+│   ├── .paths.json
 │   └── .initialized
 └── .workflow/
     ├── launch.js

package/init.js

@@ -17,21 +17,25 @@ const path      = require('path');
 let prompts;
 try { prompts = require('prompts'); } catch { prompts = null; }
 
-const arrowSelect = async (message, choices, rl) => {
+const arrowSelect = async (message, choices, rl, showBack = false) => {
+  const allChoices = showBack
+    ? [...choices, { label: dim('← Restart configuration') }]
+    : choices;
+
   if (prompts && process.stdin.isTTY) {
     const res = await prompts({
       type:    'select',
       name:    'value',
       message,
-      choices: choices.map((c, i) => ({ title: typeof c === 'string' ? c : c.label, value: i })),
+      choices: allChoices.map((c, i) => ({ title: typeof c === 'string' ? c : c.label, value: i })),
     }, { onCancel: () => process.exit(0) });
     return res.value ?? 0;
   }
-  choices.forEach((c, i) => console.log(`  ${dim(`${i + 1}.`)} ${typeof c === 'string' ? c : c.label}`));
+  allChoices.forEach((c, i) => console.log(`  ${dim(`${i + 1}.`)} ${typeof c === 'string' ? c : c.label}`));
   return new Promise(resolve => {
-    rl.question(`\n  Select (1-${choices.length}): `, ans => {
+    rl.question(`\n  Select (1-${allChoices.length}): `, ans => {
       const n = parseInt(ans) - 1;
-      resolve(!isNaN(n) && n >= 0 && n < choices.length ? n : 0);
+      resolve(!isNaN(n) && n >= 0 && n < allChoices.length ? n : 0);
     });
   });
 };
@@ -474,20 +478,23 @@ const showList = (items, showSkip = false) => {
   if (showSkip) console.log(`  ${dim('0.')} Skip ${dim('(agent will propose when needed)')}`);
 };
 
+// Sentinel value returned when user picks ← Restart
+const BACK = Symbol('BACK');
+
 const selectRequired = async (prompt, items) => {
-  console.log(`\n${bold(prompt)}`);
-  const idx = await arrowSelect(prompt, items.map(i => ({ label: typeof i === 'string' ? i : i.label })), rl);
+  const idx = await arrowSelect(prompt, items.map(i => ({ label: typeof i === 'string' ? i : i.label })), rl, true);
+  if (idx === items.length) return BACK;
   return items[idx];
 };
 
 const selectOptional = async (prompt, items) => {
   if (!items || items.length === 0) return null;
-  console.log(`\n${bold(prompt)}`);
   const choices = [
     ...items.map(i => ({ label: typeof i === 'string' ? i : i.label })),
     { label: dim('Skip (agent will propose when needed)') },
   ];
-  const idx = await arrowSelect(prompt, choices, rl);
+  const idx = await arrowSelect(prompt, choices, rl, true);
+  if (idx === choices.length) return BACK;
   if (idx === items.length) return null;
   return typeof items[idx] === 'string' ? items[idx] : items[idx].value;
 };
@@ -595,7 +602,7 @@ const main = async () => {
   separator();
 
   console.log(`\n${bold('Let\'s configure your project.')}`);
-  console.log(dim('  Required fields must be selected. Optional fields can be skipped (press 0 or Enter).\n'));
+  console.log(dim('  Use arrow keys to select. Optional fields can be skipped.\n'));
   console.log(dim('  Skipped fields will be resolved by the agent when first needed.\n'));
 
   // ── Project name ────────────────────────────────────────────────────────────
@@ -606,6 +613,14 @@ const main = async () => {
     if (!projectName) console.log(yellow('  Project name is required. Please enter a name.'));
   }
 
+  const restartIfBack = (val) => {
+    if (val !== BACK) return false;
+    rl.close();
+    const { spawn } = require('child_process');
+    spawn('node', [__filename], { stdio: 'inherit', cwd: ROOT }).on('exit', c => process.exit(c));
+    return true;
+  };
+
   separator();
 
   // ── Client ──────────────────────────────────────────────────────────────────
@@ -613,10 +628,14 @@ const main = async () => {
   console.log(`\n${bold(blue('Client configuration'))}`);
 
   const clientFw    = await selectRequired('* Client framework (required):', CLIENT_FRAMEWORKS);
+  if (restartIfBack(clientFw)) return;
   const clientLang  = clientFw.language;
   const clientState = await selectOptional('State management:', STATE_OPTIONS[clientFw.value] || []);
+  if (restartIfBack(clientState)) return;
   const clientUi    = await selectOptional('UI library:', UI_OPTIONS[clientFw.value] || []);
+  if (restartIfBack(clientUi)) return;
   const clientStyle = await selectOptional('Styling:', STYLING_OPTIONS);
+  if (restartIfBack(clientStyle)) return;
 
   separator();
 
@@ -656,7 +675,9 @@ const main = async () => {
     backendFw   = backendFwObj ? backendFwObj.value    : null;
     backendLang = backendFwObj ? backendFwObj.language : null;
     backendOrm  = backendFw ? await selectOptional('ORM / database layer:', ORM_OPTIONS[backendFw] || []) : null;
+    if (restartIfBack(backendOrm)) return;
     backendAuth = backendFw ? await selectOptional('Auth strategy:', AUTH_OPTIONS[backendFw] || []) : null;
+    if (restartIfBack(backendAuth)) return;
     backendType = backendFw ? 'separate' : null;
   }
 
@@ -690,6 +711,7 @@ const main = async () => {
   let ideChoice;
   while (true) {
     ideChoice = await selectRequired('* IDE / editor (required):', sortedIdeOptions);
+    if (restartIfBack(ideChoice)) return;
 
     // ── Confirmation ──────────────────────────────────────────────────────────
     console.log(`\n  Selected: ${bold(ideChoice.name)}`);

package/package.json

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