multi-agents-cli 1.0.99 → 1.1.1

package/README.md

@@ -93,7 +93,7 @@ You and agents co-build - each owning a defined part of the codebase. Agent task
 Next.js - Angular - Vue/Nuxt - SvelteKit - Vite+React - Remix
 
 ### Backend (separate)
-Express - NestJS - Fastify - FastAPI - Django
+Express - NestJS - Fastify - FastAPI - Django - Laravel - Rails
 
 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.
 
@@ -281,6 +281,22 @@ On completion, scope is validated and work merges into `main`. The final `main`
 }
 ```
 
-**Status values:** `null` (never launched) - `ACTIVE` (running) - `MISSING` (worktree deleted without completing)
+**Status values:** `null` (never launched) - `ACTIVE` (running) - `COMPLETED` (merged into main) - `MISSING` (worktree deleted without completing)
 
 Managed entirely by `agent.js` and `complete.js`. Never edit manually.
+
+---
+
+## What's new in v1.1.0
+
+**Init flow**
+- Step counter (`Step N of 12`) shown throughout the configuration flow
+- Back-navigation fully wired — go back to any previous step and resume without re-answering everything
+
+**After merge**
+- `npm run complete` now surfaces the next recommended agent explicitly based on tracking state
+- `start:client` script written into `package.json` after `client/UI` merges
+- `start:backend` script written into `package.json` after `backend/INIT` merges
+
+**Agent templates**
+- Every agent now includes a `Session Close` block — explicit next-step instructions after Definition of Done

package/core/templates/.agents/backend/API.md

@@ -256,4 +256,15 @@ An API task is complete when:
 - [ ] No business logic exists inside controllers
 - [ ] No existing endpoints outside task scope are affected
 - [ ] Code follows `{{FRAMEWORK}}` idiomatic controller patterns
-- [ ] Pre-flight checks all passed and documented if any flags were raised
+- [ ] Pre-flight checks all passed and documented if any flags were raised
+
+---
+
+## Session Close
+
+When all Definition of Done items are checked:
+
+1. Mark TASK.md complete: change `[ ] COMPLETED` to `[x] COMPLETED` at the top of TASK.md
+2. Run: `npm run complete`
+
+**Next recommended agent:** backend/AUTH

package/core/templates/.agents/backend/AUTH.md

@@ -243,4 +243,15 @@ An auth task is complete when:
 - [ ] Authentication and authorization are implemented as distinct units
 - [ ] No auth logic outside task scope is affected
 - [ ] Code follows `{{FRAMEWORK}}` and `{{AUTH}}` idiomatic patterns
-- [ ] Pre-flight checks all passed and documented if any flags were raised
+- [ ] Pre-flight checks all passed and documented if any flags were raised
+
+---
+
+## Session Close
+
+When all Definition of Done items are checked:
+
+1. Mark TASK.md complete: change `[ ] COMPLETED` to `[x] COMPLETED` at the top of TASK.md
+2. Run: `npm run complete`
+
+**Next recommended agent:** backend/DB

package/core/templates/.agents/backend/DB.md

@@ -254,4 +254,15 @@ A DB task is complete when:
 - [ ] Shared entity types exist in `CONTRACTS.md` - none defined locally
 - [ ] Soft deletes are explicitly declared if used
 - [ ] Code follows `{{ORM}}` idiomatic patterns
-- [ ] Pre-flight checks all passed and documented if any flags were raised
+- [ ] Pre-flight checks all passed and documented if any flags were raised
+
+---
+
+## Session Close
+
+When all Definition of Done items are checked:
+
+1. Mark TASK.md complete: change `[ ] COMPLETED` to `[x] COMPLETED` at the top of TASK.md
+2. Run: `npm run complete`
+
+**Next recommended agent:** backend/LOGIC

package/core/templates/.agents/backend/EVENTS.md

@@ -250,4 +250,15 @@ An events task is complete when:
 - [ ] Webhook token validation is delegated to AUTH.md - not implemented here
 - [ ] No event logic outside task scope is affected
 - [ ] Code follows `{{FRAMEWORK}}` idiomatic event patterns
-- [ ] Pre-flight checks all passed and documented if any flags were raised
+- [ ] Pre-flight checks all passed and documented if any flags were raised
+
+---
+
+## Session Close
+
+When all Definition of Done items are checked:
+
+1. Mark TASK.md complete: change `[ ] COMPLETED` to `[x] COMPLETED` at the top of TASK.md
+2. Run: `npm run complete`
+
+**Next recommended agent:** backend/JOBS

package/core/templates/.agents/backend/INIT.md

@@ -237,3 +237,14 @@ An INIT task is complete when:
 - [ ] No actual environment variable values exist anywhere in the codebase
 - [ ] No implementation exists in any shell file
 - [ ] Pre-flight checks all passed and documented if any flags were raised
+
+---
+
+## Session Close
+
+When all Definition of Done items are checked:
+
+1. Mark TASK.md complete: change `[ ] COMPLETED` to `[x] COMPLETED` at the top of TASK.md
+2. Run: `npm run complete`
+
+**Next recommended agent:** backend/API

package/core/templates/.agents/backend/JOBS.md

@@ -253,4 +253,15 @@ A jobs task is complete when:
 - [ ] No job is triggered synchronously inside the request/response cycle
 - [ ] Job payload types exist in `CONTRACTS.md` - none defined locally
 - [ ] Code follows `{{FRAMEWORK}}` idiomatic scheduling and queue patterns
-- [ ] Pre-flight checks all passed and documented if any flags were raised
+- [ ] Pre-flight checks all passed and documented if any flags were raised
+
+---
+
+## Session Close
+
+When all Definition of Done items are checked:
+
+1. Mark TASK.md complete: change `[ ] COMPLETED` to `[x] COMPLETED` at the top of TASK.md
+2. Run: `npm run complete`
+
+**Next recommended agent:** backend/TESTING

package/core/templates/.agents/backend/LOGIC.md

@@ -288,4 +288,15 @@ A backend logic task is complete when:
 - [ ] No unrelated domain rules bundled into the same service
 - [ ] No service logic outside task scope is affected
 - [ ] Code follows `{{FRAMEWORK}}` idiomatic service patterns
-- [ ] Pre-flight checks all passed and documented if any flags were raised
+- [ ] Pre-flight checks all passed and documented if any flags were raised
+
+---
+
+## Session Close
+
+When all Definition of Done items are checked:
+
+1. Mark TASK.md complete: change `[ ] COMPLETED` to `[x] COMPLETED` at the top of TASK.md
+2. Run: `npm run complete`
+
+**Next recommended agent:** backend/EVENTS

package/core/templates/.agents/backend/TESTING.md

@@ -263,4 +263,15 @@ A backend testing task is complete when:
 - [ ] No existing passing tests are broken
 - [ ] No implementation changes were made as part of this task
 - [ ] Code follows `{{FRAMEWORK}}` idiomatic test patterns
-- [ ] Pre-flight checks all passed and documented if any flags were raised
+- [ ] Pre-flight checks all passed and documented if any flags were raised
+
+---
+
+## Session Close
+
+When all Definition of Done items are checked:
+
+1. Mark TASK.md complete: change `[ ] COMPLETED` to `[x] COMPLETED` at the top of TASK.md
+2. Run: `npm run complete`
+
+**Next recommended agent:** shared/SECURITY

package/core/templates/.agents/client/ACCESSIBILITY.md

@@ -263,4 +263,15 @@ An accessibility task is complete when:
 - [ ] Semantic HTML is used correctly - ARIA supplements, not replaces
 - [ ] No visual or behavioral regressions introduced
 - [ ] Code follows `{{FRAMEWORK}}` idiomatic accessibility patterns
-- [ ] Pre-flight checks all passed and documented if any flags were raised
+- [ ] Pre-flight checks all passed and documented if any flags were raised
+
+---
+
+## Session Close
+
+When all Definition of Done items are checked:
+
+1. Mark TASK.md complete: change `[ ] COMPLETED` to `[x] COMPLETED` at the top of TASK.md
+2. Run: `npm run complete`
+
+**Next recommended agent:** shared/SECURITY  (or backend agents if not started)

package/core/templates/.agents/client/FORMS.md

@@ -231,4 +231,15 @@ A form task is complete when:
 - [ ] Form state is local unless explicitly justified otherwise
 - [ ] No payload types redeclared locally
 - [ ] Code follows `{{FRAMEWORK}}` idiomatic form patterns
-- [ ] Pre-flight checks all passed and documented if any flags were raised
+- [ ] Pre-flight checks all passed and documented if any flags were raised
+
+---
+
+## Session Close
+
+When all Definition of Done items are checked:
+
+1. Mark TASK.md complete: change `[ ] COMPLETED` to `[x] COMPLETED` at the top of TASK.md
+2. Run: `npm run complete`
+
+**Next recommended agent:** client/ROUTING

package/core/templates/.agents/client/LOGIC.md

@@ -274,4 +274,15 @@ A client logic task is complete when:
 - [ ] State and data fetching concerns are properly separated
 - [ ] Environment-specific values derive from config - nothing hardcoded
 - [ ] Code follows `{{FRAMEWORK}}` and `{{STATE}}` idiomatic patterns
-- [ ] Pre-flight checks all passed and documented if any flags were raised
+- [ ] Pre-flight checks all passed and documented if any flags were raised
+
+---
+
+## Session Close
+
+When all Definition of Done items are checked:
+
+1. Mark TASK.md complete: change `[ ] COMPLETED` to `[x] COMPLETED` at the top of TASK.md
+2. Run: `npm run complete`
+
+**Next recommended agent:** client/FORMS  (or backend/INIT if backend not yet started)

package/core/templates/.agents/client/ROUTING.md

@@ -232,4 +232,15 @@ A routing task is complete when:
 - [ ] No navigation logic exists inside components
 - [ ] No existing routes outside task scope are affected
 - [ ] Code follows `{{FRAMEWORK}}` idiomatic routing patterns
-- [ ] Pre-flight checks all passed and documented if any flags were raised
+- [ ] Pre-flight checks all passed and documented if any flags were raised
+
+---
+
+## Session Close
+
+When all Definition of Done items are checked:
+
+1. Mark TASK.md complete: change `[ ] COMPLETED` to `[x] COMPLETED` at the top of TASK.md
+2. Run: `npm run complete`
+
+**Next recommended agent:** client/TESTING

package/core/templates/.agents/client/TESTING.md

@@ -238,4 +238,15 @@ A testing task is complete when:
 - [ ] No existing passing tests are broken
 - [ ] No implementation changes were made as part of this task
 - [ ] Code follows `{{FRAMEWORK}}` idiomatic test patterns
-- [ ] Pre-flight checks all passed and documented if any flags were raised
+- [ ] Pre-flight checks all passed and documented if any flags were raised
+
+---
+
+## Session Close
+
+When all Definition of Done items are checked:
+
+1. Mark TASK.md complete: change `[ ] COMPLETED` to `[x] COMPLETED` at the top of TASK.md
+2. Run: `npm run complete`
+
+**Next recommended agent:** client/ACCESSIBILITY

package/core/templates/.agents/client/UI.md

@@ -223,4 +223,15 @@ A UI task is complete when:
 - [ ] Shared types consumed from `CONTRACTS.md` - none redeclared locally
 - [ ] Existing components outside task scope are unaffected
 - [ ] Code follows `{{FRAMEWORK}}` and `{{UI_LIBRARY}}` idiomatic patterns
-- [ ] Pre-flight checks all passed and documented if any flags were raised
+- [ ] Pre-flight checks all passed and documented if any flags were raised
+
+---
+
+## Session Close
+
+When all Definition of Done items are checked:
+
+1. Mark TASK.md complete: change `[ ] COMPLETED` to `[x] COMPLETED` at the top of TASK.md
+2. Run: `npm run complete`
+
+**Next recommended agent:** client/LOGIC

package/core/templates/.agents/shared/SECURITY.md

@@ -283,4 +283,15 @@ A security task is complete when:
 - [ ] No sensitive data is exposed unnecessarily across boundaries
 - [ ] No secrets, tokens, or keys found in source code
 - [ ] No fixes were implemented directly by this agent
-- [ ] Pre-flight checks all passed and documented if any flags were raised
+- [ ] Pre-flight checks all passed and documented if any flags were raised
+
+---
+
+## Session Close
+
+When all Definition of Done items are checked:
+
+1. Mark TASK.md complete: change `[ ] COMPLETED` to `[x] COMPLETED` at the top of TASK.md
+2. Run: `npm run complete`
+
+**Next recommended agent:** npm run complete — project is secured. Consider backend or deploy when ready.

package/core/workflow/complete.js

@@ -391,6 +391,58 @@ const main = async () => {
     }
   } catch { /* best-effort */ }
 
+  // ── Write start:client / start:backend into root package.json ───────────────
+
+  try {
+    const CLIENT_START = {
+      'Next.js':    'npm run dev',
+      'Nuxt':       'npm run dev',
+      'SvelteKit':  'npm run dev',
+      'Remix':      'npm run dev',
+      'Vite+React': 'npm run dev',
+      'Angular':    'npx ng serve',
+    };
+    const BACKEND_START = {
+      'NestJS':   'npm run start:dev',
+      'Express':  'npm run dev',
+      'Fastify':  'npm run dev',
+      'Django':   'python manage.py runserver',
+      'FastAPI':  'uvicorn main:app --reload',
+      'Laravel':  'php artisan serve',
+      'Rails':    'bin/rails server',
+    };
+
+    const pkgPath = path.join(ROOT, 'package.json');
+    if (fs.existsSync(pkgPath)) {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      if (!pkg.scripts) pkg.scripts = {};
+
+      const parts = branchName.split('/');
+      const mergedScope = parts.length >= 4 ? parts[1] : null;
+      const mergedAgent = parts.length >= 4 ? parts[2].toUpperCase() : null;
+
+      if (mergedScope === 'client' && mergedAgent === 'UI') {
+        const fw = config.client && config.client.framework;
+        const cmd = CLIENT_START[fw];
+        if (cmd && !pkg.scripts['start:client']) {
+          pkg.scripts['start:client'] = cmd;
+          fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf8');
+          console.log(`  ${green('✓')} start:client added to package.json (${cmd})`);
+        }
+      }
+
+      if (mergedScope === 'backend' && mergedAgent === 'INIT') {
+        const fw = config.backend && config.backend.framework;
+        const cmd = BACKEND_START[fw];
+        if (cmd && !pkg.scripts['start:backend']) {
+          pkg.scripts['start:backend'] = cmd;
+          fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf8');
+          console.log(`  ${green('✓')} start:backend added to package.json (${cmd})`);
+        }
+      }
+    }
+  } catch { /* best-effort */ }
+
   // ── Update scaffold flags ──────────────────────────────────────────────────
 
   try {
@@ -442,11 +494,53 @@ const main = async () => {
   if (_agent) console.log(`  ${dim('Agent')}  : ${green(_agent)} ${dim('(' + _scope + ')')}`);
   if (_task)  console.log(`  ${dim('Task')}   : ${dim(_task)}`);
   console.log(`  ${dim('Branch')} : ${green(branchName)} merged into ${green('main')}\n`);
-  console.log(`  ${bold('What to do next:')}\n`);
-  console.log(`  Start a new task:`);
-  console.log(`  ${cyan('npm run agent')}\n`);
-  separator();
-  console.log('');
+
+  // ── Derive next step from tracking ──────────────────────────────────────────
+  const AGENT_ORDER = {
+    client:  ['UI', 'LOGIC', 'FORMS', 'ROUTING', 'TESTING', 'ACCESSIBILITY'],
+    backend: ['INIT', 'API', 'LOGIC', 'AUTH', 'DB', 'TESTING', 'EVENTS', 'JOBS'],
+    shared:  ['SECURITY'],
+  };
+  const SCOPE_ORDER = ['client', 'backend', 'shared'];
+
+  try {
+    const _tracking = guards.loadTracking(ROOT, config);
+
+    const findNextInScope = (scope) => {
+      const order = AGENT_ORDER[scope] || [];
+      for (const a of order) {
+        const slot = (_tracking[scope] || {})[a];
+        if (!slot || (slot.status !== 'COMPLETED' && slot.status !== 'ACTIVE')) return a;
+      }
+      return null;
+    };
+
+    let nextScope = null;
+    let nextAgent = null;
+
+    const scopesToCheck = [_scope, ...SCOPE_ORDER.filter(s => s !== _scope)];
+    for (const s of scopesToCheck) {
+      const n = findNextInScope(s);
+      if (n) { nextScope = s; nextAgent = n; break; }
+    }
+
+    separator();
+    console.log(`\n  ${bold('What to do next:')}`);
+
+    if (nextAgent) {
+      console.log(`\n  ${green('→')} ${bold(nextAgent)} ${dim('(' + nextScope + ')')}`);
+      console.log(`\n  ${cyan('npm run agent')}`);
+      console.log(`  ${dim('Select: ' + nextScope + ' → ' + nextAgent)}`);
+    } else {
+      console.log(`\n  ${cyan('npm run agent')}`);
+    }
+  } catch {
+    separator();
+    console.log(`\n  ${bold('What to do next:')}\n`);
+    console.log(`  ${cyan('npm run agent')}`);
+  }
+
+  console.log('\n');
 
 
   // ── Backend/INIT launch prompt (if user chose 'after' during LOGIC session) ──

package/lib/questions-flow.js

@@ -2,7 +2,7 @@
 
 // ── Imports ───────────────────────────────────────────────────────────────────
 
-const { dim, bold, blue, green, cyan, separator, arrowSelect, arrowConfirm, selectRequired, selectOptional } = require('./ui');
+const { dim, bold, blue, green, cyan, separator, arrowSelect, arrowConfirm, selectRequired, selectOptional, stepHeader } = require('./ui');
 const { BACK, RESTART } = require('./steps');
 const {
   CLIENT_FRAMEWORKS, BACKEND_FRAMEWORKS, FRAMEWORK_VERSION_FALLBACK,
@@ -21,6 +21,7 @@ const buildStepDefs = (IDE_CANDIDATES) => [
   {
     name: 'clientFw',
     run: async (machine, answers) => {
+      stepHeader(1, 12);
       console.log(`\n${bold(blue('Client configuration'))}`);
       return await selectRequired('* Client framework (required):', CLIENT_FRAMEWORKS, machine, 0);
     },
@@ -30,6 +31,7 @@ const buildStepDefs = (IDE_CANDIDATES) => [
   {
     name: 'clientFwVersion',
     run: async (machine, answers) => {
+      stepHeader(2, 12);
       const fw = answers.clientFw;
       const versions = await fetchLatestVersions(fw.value) || FRAMEWORK_VERSION_FALLBACK[fw.value] || [];
       if (!versions.length) return null; // skip silently
@@ -56,6 +58,7 @@ const buildStepDefs = (IDE_CANDIDATES) => [
   {
     name: 'clientState',
     run: async (machine, answers) => {
+      stepHeader(3, 12);
       const opts = STATE_OPTIONS[answers.clientFw.value] || [];
       return await selectOptional('State management:', opts, machine, 2);
     },
@@ -65,6 +68,7 @@ const buildStepDefs = (IDE_CANDIDATES) => [
   {
     name: 'clientUi',
     run: async (machine, answers) => {
+      stepHeader(4, 12);
       const opts = UI_OPTIONS[answers.clientFw.value] || [];
       return await selectOptional('UI library:', opts, machine, 3);
     },
@@ -74,6 +78,7 @@ const buildStepDefs = (IDE_CANDIDATES) => [
   {
     name: 'clientStyle',
     run: async (machine, answers) => {
+      stepHeader(5, 12);
       return await selectOptional('Styling:', STYLING_OPTIONS, machine, 4);
     },
   },
@@ -82,6 +87,7 @@ const buildStepDefs = (IDE_CANDIDATES) => [
   {
     name: 'useIntegratedBackend',
     run: async (machine, answers) => {
+      stepHeader(6, 12);
       const fw = answers.clientFw;
       if (!fw.integratedBackend) return false; // skip — not applicable
 
@@ -98,6 +104,7 @@ const buildStepDefs = (IDE_CANDIDATES) => [
   {
     name: 'backendFwObj',
     run: async (machine, answers) => {
+      stepHeader(7, 12);
       if (answers.useIntegratedBackend) return null; // skip
 
       separator();
@@ -121,6 +128,7 @@ const buildStepDefs = (IDE_CANDIDATES) => [
   {
     name: 'backendFwVersion',
     run: async (machine, answers) => {
+      stepHeader(8, 12);
       const fwObj = answers.backendFwObj;
       if (!fwObj) return null; // skip — no backend selected
 
@@ -147,6 +155,7 @@ const buildStepDefs = (IDE_CANDIDATES) => [
   {
     name: 'backendDb',
     run: async (machine, answers) => {
+      stepHeader(9, 12);
       if (!answers.backendFwObj) return null;
       return await selectOptional('Database type:', DB_OPTIONS, machine, 8);
     },
@@ -156,6 +165,7 @@ const buildStepDefs = (IDE_CANDIDATES) => [
   {
     name: 'backendOrm',
     run: async (machine, answers) => {
+      stepHeader(10, 12);
       const { backendFwObj, backendDb } = answers;
       if (!backendFwObj || !backendDb) return null;
       const ormChoices = ORM_OPTIONS_BY_DB[backendDb] || ORM_OPTIONS[backendFwObj.value] || [];
@@ -167,6 +177,7 @@ const buildStepDefs = (IDE_CANDIDATES) => [
   {
     name: 'backendAuth',
     run: async (machine, answers) => {
+      stepHeader(11, 12);
       const { backendFwObj } = answers;
       if (!backendFwObj) return null;
       return await selectOptional('Auth strategy:', AUTH_OPTIONS[backendFwObj.value] || [], machine, 10);
@@ -177,6 +188,7 @@ const buildStepDefs = (IDE_CANDIDATES) => [
   {
     name: 'ideChoice',
     run: async (machine, answers) => {
+      stepHeader(12, 12);
       separator();
       console.log(`\n${bold(blue('Environment'))}`);
 

package/lib/steps.js

@@ -103,13 +103,25 @@ const runQuestions = async (stepDefs, machine) => {
     if (result === RESTART) return RESTART;
 
     if (result === BACK) {
-      if (i === 0) return RESTART; // nowhere to go back to from step 0
+      if (i === 0) return RESTART; // nowhere to go back from step 0
+      machine.enterBackNav(i);     // record where back-nav started
       const popped = machine.pop();
       if (popped) delete answers[popped.stepName];
       i--;
       continue;
     }
 
+    if (result === CONTINUE) {
+      // User chose to resume — skip forward to where they first pressed Back
+      const resumeTarget = machine.resumeIndex ?? i + 1;
+      machine.exitBackNav();
+      i = resumeTarget;
+      continue;
+    }
+
+    // Normal answer — if re-answering during back-nav, exit back-nav mode
+    if (machine.inBackNav) machine.exitBackNav();
+
     machine.push(i, def.name, result);
     answers[def.name] = result;
     i++;

package/lib/ui.js

@@ -109,6 +109,13 @@ const renderTrajectoryLines = (lines) => {
   });
 };
 
+// ── Step progress header ─────────────────────────────────────────────────────
+
+const stepHeader = (stepIndex, totalSteps) => {
+  console.log(`
+  ${dim(`Step ${stepIndex} of ${totalSteps}`)}`);
+};
+
 // ── Step selection helpers ────────────────────────────────────────────────────
 
 const { BACK, RESTART } = require('./steps');
@@ -150,6 +157,7 @@ const selectOptional = async (prompt, items, stepMachine, stepIndex) => {
 // ── Exports ───────────────────────────────────────────────────────────────────
 
 module.exports = {
+  stepHeader,
   c, bold, green, yellow, dim, cyan, blue, red,
   rl, ask,
   arrowSelect, arrowConfirm,

package/package.json

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