yadflow 2.13.0 → 2.14.0

package/CHANGELOG.md

@@ -1,9 +1,9 @@
-# [2.13.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.12.0...v2.13.0) (2026-06-16)
+# [2.14.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.13.0...v2.14.0) (2026-06-21)
 
 
 ### Features
 
-* **docs:** make the report the main documentation, mount the SPA under /app/ ([#71](https://github.com/abdelrahmannasr/yadflow/issues/71)) ([1993e4d](https://github.com/abdelrahmannasr/yadflow/commit/1993e4dc282df281474ca1923acd52dbd1262dcb))
+* yad next driver, precondition guards, solo mode, and guided setup interview ([#72](https://github.com/abdelrahmannasr/yadflow/issues/72)) ([7125c9d](https://github.com/abdelrahmannasr/yadflow/commit/7125c9d80043cb282a7be4f08dfaa95ddf94594a))
 
 # [2.2.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.1.0...v2.2.0) (2026-06-14)
 

package/README.md

@@ -85,7 +85,8 @@ with `npx` from your **product hub** repo — no clone needed.
 
 | Command | What it does |
 |---------|--------------|
-| `npx yadflow setup` | Guided first-run wizard (the steps below). |
+| `npx yadflow setup` | Guided first-run wizard — a short **profile interview** (solo/team, greenfield/brownfield, monorepo/separate) then the branched steps below. Pre-answer for CI/scripts with `--solo`/`--team <n>`, `--greenfield`/`--brownfield`, `--monorepo`/`--separate`, `--tools`. |
+| `yad next [<epic>]` | **Where am I / what next.** With no epic: project-wide orientation — the one next action (run setup, start an epic, or the single active epic's step). With an epic: that epic's exact next action (a skill to invoke or a `yad` command to run). `yad next <epic> --check <step>` exits non-zero when a step is run out of order (the precondition guard); `yad next --all` lists every epic's next action. |
 | `npx yadflow check` | Read-only report: what is **missing** / **outdated** (drifted) / **stale** (code-context) / **legacy** (pre-2.0 `sdlc-*` names) vs the bundled manifest. |
 | `npx yadflow check --fix` | Reconcile: fill what is missing **and** update what changed — touches nothing already correct. |
 | `npx yadflow update` | Apply drift only (alias for `check --fix --scope=changed`). Also migrates a pre-2.0 install in place: `sdlc-*` skill copies and marker-owned `sdlc-*.yml` CI files are replaced by their `yad-*` names (a same-named file *you* authored is never touched). |
@@ -120,6 +121,13 @@ The merge click is the human approval act, so front steps still never `machine_a
 **revoked when the reviewed artifact actually changes** (re-hash), giving reviewers a fresh pass. With no
 hub platform / no `gh`/`glab`, the gate degrades to file-only with no error.
 
+**Solo mode.** A lone developer can't approve their own PR on GitHub, so an approval requirement would
+deadlock them. Opt in (`yad setup --solo`, recorded as `solo: true` in `.sdlc/hub.json`) and the gate
+**waives the approval requirement only** — the review PR/MR and its merge stay, so CI still runs on the
+PR and the **merge** advances the step. Net: the gate passes on *merged + all threads resolved*. It's a
+documented, reversible relaxation; `yad doctor` warns if branch protection still "requires approvals"
+(which would block the solo dev's own merge).
+
 **Event-driven sync.** Wire the hub once (`yad check --fix` installs `.github/workflows/yad-gate-sync.yml`,
 or the GitLab fragment + schedule) and every **approval, change request, and merge** on a review PR/MR
 triggers `yad gate ci` in the hub's own CI: the ledger updates land directly on the hub's default branch
@@ -132,29 +140,33 @@ a manual `yad gate sync` racing CI, or GitLab pipelines — two simultaneous syn
 *commits* via the rebase retry but each works from the state it read at start, so the rarer of two
 simultaneous advancements can be lost; the next event or scheduled sweep re-syncs and converges.
 
-### What `setup` walks you through (10 steps)
+### What `setup` walks you through (a guided, branching interview)
+
+Setup opens with a short **profile interview** — *solo or team (how many)? greenfield or brownfield?
+monorepo or separate repos?* — and the answers (recorded in `.sdlc/hub.json` as `solo` + `profile`)
+branch the rest so you only answer what your situation needs. Each step prints inline guidance (what it
+does / why / what to enter / what skipping means), and the step count adapts.
 
+0. **Profile** — the three questions above, plus "configure optional tools now?". Pre-answer for
+   CI/scripts with `--solo`/`--team <n>`, `--greenfield`/`--brownfield`, `--monorepo`/`--separate`, `--tools`.
 1. **Preflight** — confirm the hub is a git repo (offers `git init`); check `git`/`node`/`npx`.
 2. **Install the module** — copy all 30 `yad-*` skills into the IDE skill dirs you pick
    (`.claude/`, `.agents/`, `.zencoder/`, `.opencode/`) and register `_bmad/sdlc/`.
 3. **Hub platform & roster** — detect GitHub/GitLab from the remote; record reviewers → `.sdlc/hub.json`.
-   Edit the roster any time afterwards with `yad roster` (no need to re-run the whole wizard).
-4. **Connect a design tool** — record the design tool (Figma / pencil / none) → `.sdlc/design.json` so
-   the UI step can materialize the design; the MCP itself is confirmed later by `yad-connect-design`.
-5. **Connect a testing tool** — record the testing tool (Playwright / cypress / pytest / none) →
-   `.sdlc/testing.json` so the test-cases step can implement the automation; the MCP itself is confirmed
-   later by `yad-connect-testing`.
-6. **Connect a learning tool** — record the learning tool (DeepTutor / none) → `.sdlc/learning.json` so
-   the learning layer can tutor the team; the CLI + knowledge base are confirmed later by
-   `yad-connect-learning`.
-7. **Connect code repos** — register each repo into `.sdlc/repos.json` and cache a Repomix pack.
-8. **Wire each repo** — CI gates, PR/MR template, and review-comment scaffold.
-9. **AI review** — optionally write `.coderabbit.yaml`.
-10. **Done** — stamp `.sdlc/cli-version.json` and hand off the AI-only steps (code-maps; first epic).
+   **Solo skips the roster** (you review by merging your own PR). Edit the roster any time with `yad roster`.
+4. **Optional tools** — design (Figma/pencil), testing (Playwright/cypress/pytest), learning (DeepTutor).
+   Configure now, or **defer with one prompt** → all recorded as `none` (connect later with the
+   `yad-connect-*` skills; the MCPs/CLIs are confirmed there).
+5. **Connect code repos** — register repos into `.sdlc/repos.json`. **Monorepo** connects one repo and
+   skips domain-owner prompts; **greenfield** skips the Repomix pack (run `yad repo refresh` once it has code).
+6. **Wire each repo** — CI gates, PR/MR template, and review-comment scaffold.
+7. **AI review** — optionally write `.coderabbit.yaml`.
+8. **Done** — stamp `.sdlc/cli-version.json` and print a **profile-tailored next step** (brownfield →
+   `yad-backfill` first; everyone → `yad next` and your first epic via `yad-epic`).
 
 The deterministic file work runs automatically; the AI-only steps are handed to the Claude Code skills
 with a printed next-action. Re-run `… check --fix` any time the workflow updates — it never re-asks for
-input you already gave.
+input you already gave; re-running `setup` carries your profile forward.
 
 **Releases:** automated via semantic-release on merge to `main` (Conventional Commits → npm, with
 provenance). See [`RELEASING.md`](RELEASING.md).

package/bin/yad.mjs

@@ -13,11 +13,14 @@ import { runRepo } from '../cli/repo.mjs';
 import { runRoster } from '../cli/roster.mjs';
 import { runDocs } from '../cli/docs.mjs';
 import { runDoctor } from '../cli/doctor.mjs';
+import { runNext } from '../cli/next.mjs';
 
 const HELP = `${c.bold('yad')} — setup, review-gate & build helpers for the SDLC Workflow module  ${c.dim('v' + VERSION)}
 
 ${c.bold('Setup & maintenance')}
-  yad setup            Guided first-run setup (install module, connect & wire repos)
+  yad setup            Guided first-run setup (profile interview, install, connect & wire repos)
+                       profile flags: --solo | --team <n>, --greenfield | --brownfield,
+                       --monorepo | --separate, --tools (configure design/testing/learning now)
   yad check            Report what is missing / drifted / stale / legacy (read-only)
   yad check --fix      Reconcile: fill what is missing, update what changed
   yad update           Apply drift only (alias for: check --fix --scope=changed);
@@ -33,6 +36,12 @@ ${c.bold('Reviewer roster')}
   yad roster revoke <name> <repo> <role...>  Remove role(s) for a repo
   yad roster remove <login>            Delete a member from the roster
 
+${c.bold('Where am I / what next')}
+  yad next                             Project-wide: the one next action to take (or run setup)
+  yad next <epic>                      The single next action for one epic (skill or yad command)
+  yad next <epic> --check <step>       Exit 0 if <step> is runnable now, else 1 (precondition guard)
+  yad next --all                       Every active epic's next action at once
+
 ${c.bold('Review gate (front half)')}
   yad gate open <epic> <artifact>      Open the review PR/MR; mark the step in_review
   yad gate sync <epic> [artifact]      Pull PR state -> ledger; advance on approved+resolved+merged
@@ -75,7 +84,7 @@ ${c.bold('Options')}
   -h, --help            Show this help
   -v, --version         Print version`;
 
-const VALUE_FLAGS = new Set(['--dir', '--type', '--message', '--task', '--ai', '--risk', '--repo', '--platform', '--base', '--title', '--scope', '--branch', '--pr', '--epic', '--name', '--email', '--roles']);
+const VALUE_FLAGS = new Set(['--dir', '--type', '--message', '--task', '--ai', '--risk', '--repo', '--platform', '--base', '--title', '--scope', '--branch', '--pr', '--epic', '--name', '--email', '--roles', '--team']);
 
 function parseArgs(argv) {
   const o = { _: [], dir: process.cwd(), fix: false, force: false, scope: 'all' };
@@ -86,7 +95,19 @@ function parseArgs(argv) {
     else if (a === '--contract-change') o.contractChange = true;
     else if (a === '--no-push') o.noPush = true;
     else if (a === '--overview') o.overview = true;
-    else if (a === '--check') o.check = true;
+    // `--check` is a bare boolean for `docs sync --check`, but takes a value for
+    // `next <epic> --check <step>`. Only the `next` command consumes the following token as a value —
+    // scoping it to `next` keeps `docs sync --check overview` (and any other command) from swallowing a
+    // positional. `o._[0]` is the command, already pushed by the time `--check` is seen in normal use.
+    else if (a === '--check') { const v = argv[i + 1]; o.check = (o._[0] === 'next' && v !== undefined && !v.startsWith('-')) ? argv[++i] : true; }
+    else if (a === '--all') o.all = true;
+    // setup profile flags (pre-answer the Step 0 interview, for CI/scripts)
+    else if (a === '--solo') o.solo = true;
+    else if (a === '--greenfield') o.greenfield = true;
+    else if (a === '--brownfield') o.brownfield = true;
+    else if (a === '--monorepo') o.monorepo = true;
+    else if (a === '--separate') o.separate = true;
+    else if (a === '--tools') o.tools = true;
     else if (a === '--refresh') o.refresh = true;
     else if (a === '--wire') o.wire = true;
     else if (a === '--dry-run') o.dryRun = true;
@@ -117,7 +138,11 @@ async function main() {
   const today = new Date().toISOString().slice(0, 10);
   switch (cmd) {
     case 'setup':
-      await runSetup(o.dir, { today, force: o.force });
+      await runSetup(o.dir, {
+        today, force: o.force,
+        solo: o.solo, team: o.team, greenfield: o.greenfield, brownfield: o.brownfield,
+        monorepo: o.monorepo, separate: o.separate, tools: o.tools,
+      });
       break;
     case 'check':
       await reconcile(o.dir, { fix: o.fix, scope: o.scope, force: o.force, today });
@@ -128,6 +153,13 @@ async function main() {
     case 'doctor':
       await runDoctor(o.dir, { json: o.json });
       break;
+    case 'next': {
+      const [, epic] = o._;
+      // `--check` with no step is a malformed guard call — fail loudly rather than silently print.
+      if (o.check === true) { log(c.red('usage: yad next <epic> --check <step>')); process.exitCode = 1; break; }
+      await runNext(o.dir, { epic, check: typeof o.check === 'string' ? o.check : undefined, all: o.all });
+      break;
+    }
     case 'gate': {
       const [, action, epic, artifact] = o._;
       // `gate ci` takes no positionals — epic/artifact come from --branch (or a sweep of all PRs).

package/cli/doctor.mjs

@@ -12,6 +12,12 @@ import { cliFor, validateLogin, hostFromGitUrl } from './platform.mjs';
 
 const MIN_NODE = 18;
 
+// Solo mode (a lone developer): approval waived, merge + resolved threads still gate. Persisted in
+// hub.json. Mirrors gate.mjs / next.mjs.
+const isSolo = (hub) => !!(hub && (hub.solo === true || hub.review_gate?.solo === true));
+// owner/repo slug from a git url (https or ssh), for the branch-protection probe.
+const repoSlug = (url) => ((url || '').match(/[:/]([^/:]+\/[^/]+?)(?:\.git)?$/) || [])[1] || null;
+
 // Each check: { id, section, status: 'ok'|'warn'|'fail', message, hint? }
 function check(checks, id, section, status, message, hint = '') {
   checks.push({ id, section, status, message, ...(hint ? { hint } : {}) });
@@ -65,6 +71,7 @@ export function projectChecks(checks, root) {
     else if (hub.roster !== undefined && !Array.isArray(hub.roster)) check(checks, 'hub', 'project', 'fail', `${PROJECT_FILES.hubConfig}: \`roster\` must be an array [YAD-STATE-002]`, 'fix the file or re-run `yad setup`');
     else {
       check(checks, 'hub', 'project', 'ok', `hub: ${hub.platform || 'file-only'}, ${(hub.roster || []).length} reviewer(s)`);
+      if (isSolo(hub)) check(checks, 'solo', 'project', 'ok', 'mode: solo — approval waived; the PR merge + resolved threads gate the step');
       // platform CLI + auth (best-effort; auth probing is the user's own session)
       const cli = cliFor(hub.platform);
       if (cli) {
@@ -86,6 +93,18 @@ export function projectChecks(checks, root) {
           }
           if (bad.length) check(checks, 'roster', 'project', 'warn', `roster login(s) not found on ${hub.platform}: ${bad.join(', ')}`, 'fix the login or re-run `yad setup` (they cannot satisfy a gate)');
           else check(checks, 'roster', 'project', 'ok', `roster: ${(hub.roster || []).length} member(s) validated on ${hub.platform}`);
+          // Solo + GitHub: a branch that "requires approvals" would block the solo dev's own merge
+          // (they can't approve their own PR). Best-effort probe; a 404 (no protection) is fine.
+          if (isSolo(hub) && hub.platform === 'github') {
+            const slug = repoSlug(hub.git_url) || repoSlug(run('git', ['remote', 'get-url', 'origin'], { cwd: root }).stdout);
+            const br = hub.default_branch || 'main';
+            if (slug) {
+              const probe = run('gh', ['api', `repos/${slug}/branches/${br}/protection/required_pull_request_reviews`, '--jq', '.required_approving_review_count']);
+              if (probe.ok && Number(probe.stdout) > 0) {
+                check(checks, 'solo-branch-protection', 'project', 'warn', `solo mode but ${br} requires ${probe.stdout} approval(s) — you cannot approve your own PR, so the merge will be blocked`, `relax "Require approvals" in ${slug} branch protection for ${br}`);
+              }
+            }
+          }
         }
       }
     }
@@ -173,7 +192,8 @@ export function projectChecks(checks, root) {
       if (!exists(repoRoot)) { check(checks, `repo:${repo.name}`, 'project', 'fail', `${repo.name}: path ${repo.path} does not exist [YAD-STATE-003]`, 'fix the path in repos.json or re-connect the repo'); continue; }
       const head = gitHead(repoRoot);
       if (!head) { check(checks, `repo:${repo.name}`, 'project', 'fail', `${repo.name}: ${repo.path} is not a git repository (or has no commits) [YAD-STATE-003]`, 'init/clone the repo, then re-connect it'); continue; }
-      if (repo.syncedHead && head !== repo.syncedHead) check(checks, `repo:${repo.name}`, 'project', 'warn', `${repo.name}: code-context is stale (HEAD moved since last pack)`, 'run `yad repo refresh ' + repo.name + '`');
+      if (!repo.syncedHead) check(checks, `repo:${repo.name}`, 'project', 'warn', `${repo.name}: registered without a code-context pack (greenfield)`, 'run `yad repo refresh ' + repo.name + '` once it has code');
+      else if (head !== repo.syncedHead) check(checks, `repo:${repo.name}`, 'project', 'warn', `${repo.name}: code-context is stale (HEAD moved since last pack)`, 'run `yad repo refresh ' + repo.name + '`');
       else check(checks, `repo:${repo.name}`, 'project', 'ok', `${repo.name}: git repo, context fresh`);
     }
     if (!registry.repos.length) check(checks, 'repos', 'project', 'warn', 'no code repos registered', 'run `yad setup` to connect one');

package/cli/epic-state.mjs

@@ -158,6 +158,7 @@ export function gatePredicate({
   defaultReviewers = 1,
   threadsResolved = true,
   merged = true,
+  solo = false,
 }) {
   const forStep = approvals.filter((a) => a.step === step.id && a.status === 'approved');
   // Revoke-on-change: an approval bound to a stale content hash no longer counts.
@@ -168,19 +169,24 @@ export function gatePredicate({
   const reviewers = uniqueBy(live.filter((a) => a.role === 'reviewer'), 'approver');
   const domainOwners = live.filter((a) => a.role === 'domain-owner');
 
-  const missing = [];
-  if (owners.length < 1) missing.push('1 owner approval');
-  if (reviewers.length < defaultReviewers) {
-    missing.push(`${defaultReviewers - reviewers.length} reviewer approval(s)`);
-  }
   const escalate = isEscalated(step);
-  if (escalate) {
-    for (const d of touchedDomains) {
-      if (!domainOwners.some((a) => a.domain === d)) missing.push(`domain-owner for ${d}`);
+  const missing = [];
+  // Solo mode waives the APPROVAL requirements entirely (you can't approve your own PR on GitHub) —
+  // merge + resolved threads are what advance the step. Team mode is unchanged.
+  if (!solo) {
+    if (owners.length < 1) missing.push('1 owner approval');
+    if (reviewers.length < defaultReviewers) {
+      missing.push(`${defaultReviewers - reviewers.length} reviewer approval(s)`);
+    }
+    if (escalate) {
+      for (const d of touchedDomains) {
+        if (!domainOwners.some((a) => a.domain === d)) missing.push(`domain-owner for ${d}`);
+      }
     }
   }
   const approvalsSatisfied = missing.length === 0;
-  if (stale.length) missing.unshift(`${stale.length} approval(s) revoked — artifact changed; re-approve`);
+  // A stale approval only matters when approvals are required (team mode); in solo they are moot.
+  if (!solo && stale.length) missing.unshift(`${stale.length} approval(s) revoked — artifact changed; re-approve`);
   if (!threadsResolved) missing.push('unresolved review comments');
   if (!merged) missing.push('review PR/MR not merged');
 
@@ -191,7 +197,7 @@ export function gatePredicate({
     staleDropped: stale.length,
     passed: approvalsSatisfied && threadsResolved && merged,
     missing,
-    rule: escalate ? (step.id === 'stories-review' ? 'per-repo' : 'escalated') : 'base',
+    rule: solo ? 'solo' : escalate ? (step.id === 'stories-review' ? 'per-repo' : 'escalated') : 'base',
   };
 }
 
@@ -235,4 +241,73 @@ export function markInReview(state, step) {
   return state;
 }
 
+// The front authoring step a `yad next` action maps to — the skill the user invokes for that step.
+// Review (review+approve) steps are driven by the `yad gate` CLI, not a skill, so they are not here.
+export const STEP_SKILL = {
+  analysis: 'yad-analysis',
+  epic: 'yad-epic',
+  architecture: 'yad-architecture',
+  'ui-design': 'yad-ui',
+  stories: 'yad-stories',
+  'test-cases': 'yad-test-cases',
+};
+
+// PURE precondition guard. Is `stepId` runnable right now? A step is runnable iff every step BEFORE it
+// in the chain is `done` and the step itself is not already `done`. With no state yet (greenfield), the
+// only runnable steps are the entry authoring steps (analysis | epic). Used by `yad next --check`
+// (the Phase B rail) and by the driver. No FS / network.
+export function preconditionsMet(state, stepId) {
+  if (!state || !Array.isArray(state.steps)) {
+    const ok = stepId === 'epic' || stepId === 'analysis';
+    return { ok, blockedBy: null, reason: ok ? 'entry step (no epic seeded yet)' : `start with yad-epic — no epic state for '${stepId}'` };
+  }
+  const i = state.steps.findIndex((s) => s.id === stepId);
+  if (i === -1) return { ok: false, blockedBy: null, reason: `unknown step '${stepId}'` };
+  if (state.steps[i].status === 'done') return { ok: false, blockedBy: null, reason: `${stepId} is already done` };
+  const blocker = state.steps.slice(0, i).find((s) => s.status !== 'done');
+  if (blocker) return { ok: false, blockedBy: blocker.id, reason: `${blocker.id} has not passed yet` };
+  return { ok: true, blockedBy: null, reason: 'ready' };
+}
+
+// PURE next-action resolver for ONE epic's ledger — what `yad next <epic>` prints. Reads state + the
+// recorded review PRs only. kind:
+//   'new'         — no epic state yet (seed one with yad-epic)
+//   'author'      — invoke a front authoring skill (STEP_SKILL)
+//   'review-open' — open the review PR/MR (`yad gate open`)
+//   'review-sync' — a review PR/MR is open; sync its state (`yad gate sync`)
+//   'build'       — front half approved (ready-for-build); the build half can run
+export function nextAction(ledger, { epic } = {}) {
+  const state = ledger?.state;
+  const epicId = epic || state?.epicId || null;
+  if (!state) return { epicId, kind: 'new', skill: 'yad-epic', why: 'no epic state yet — seed it with yad-epic' };
+
+  // The parallel test-cases track stays workable even once the epic is ready-for-build.
+  const tc = state.steps.find((s) => s.id === 'test-cases');
+  const tcOpen = !!tc && tc.status !== 'done' && tc.status !== 'blocked';
+  const parallel = tcOpen ? { step: 'test-cases', skill: STEP_SKILL['test-cases'], artifact: tc.artifact } : null;
+
+  if (state.currentStep === 'ready-for-build') {
+    return { epicId, kind: 'build', step: 'ready-for-build', status: 'ready-for-build', parallel,
+      why: 'front half approved — the build half can run' };
+  }
+
+  const step = state.steps.find((s) => s.id === state.currentStep)
+    || state.steps.find((s) => s.status !== 'done');
+  if (!step) return { epicId, kind: 'build', step: 'ready-for-build', parallel, why: 'all front steps are done' };
+
+  if (step.type === 'author') {
+    return { epicId, kind: 'author', step: step.id, status: step.status, parallel,
+      skill: STEP_SKILL[step.id] || null, artifact: step.artifact,
+      why: `${step.id} is ${step.status} — author ${step.artifact}` };
+  }
+
+  // review+approve: open the review PR if none is recorded yet, else sync the open one.
+  const pr = (ledger.hubPrs || []).find((p) => artifactBase(p.artifact) === artifactBase(step.artifact));
+  const verb = pr ? 'sync' : 'open';
+  return { epicId, kind: pr ? 'review-sync' : 'review-open', step: step.id, status: step.status,
+    artifact: step.artifact, pr: pr ? pr.number : null, parallel,
+    command: `yad gate ${verb} ${epicId} ${step.artifact}`,
+    why: pr ? `review PR #${pr.number} is open — sync its state to advance` : `${step.id} is open — create the review PR/MR` };
+}
+
 export { writeJSON };

package/cli/gate.mjs

@@ -85,6 +85,11 @@ function loadHub(root) {
   return { hub, repos: registry.repos };
 }
 
+// Solo mode (a lone developer): waive the approval requirement — on GitHub you cannot approve your own
+// PR, so an approval gate would deadlock. The review PR/MR and its merge stay (CI runs on the PR; the
+// merge advances the step). Recorded per-project in hub.json by `yad setup`.
+const isSolo = (hub) => !!(hub && (hub.solo === true || hub.review_gate?.solo === true));
+
 // Re-add this step's bridge approvals from the current platform state (drop+re-add => dismissals and
 // revocations vanish idempotently; manual approvals are never touched). Preserve the artifactHash a
 // reviewer first approved against unless their review is newer (a genuine re-approval) — that is what
@@ -159,6 +164,7 @@ export async function gateSync(root, { epic, artifact, today, reader = readPr }
   const platform = hub.platform;
   const roster = hub.roster || [];
   const defaultReviewers = 1;
+  const solo = isSolo(hub);
   const epicDir = epicRoot(root, epic);
   const ledger = loadLedger(epicDir);
   if (!ledger.state) { fail(`no epic state at ${epicDir}/.sdlc/state.json`); process.exitCode = 1; return { synced: 0 }; }
@@ -195,7 +201,7 @@ export async function gateSync(root, { epic, artifact, today, reader = readPr }
 
     const pred = gatePredicate({
       step, approvals, currentHash: curHash, touchedDomains: domains,
-      defaultReviewers, threadsResolved, merged: pull.merged,
+      defaultReviewers, threadsResolved, merged: pull.merged, solo,
     });
 
     log(`  ${c.bold(pr.artifact)} ${c.dim(`(PR #${pr.number}, rule: ${pred.rule})`)}`);
@@ -382,7 +388,8 @@ export async function gateStatus(root, { epic } = {}) {
   const epicDir = epicRoot(root, epic);
   const ledger = loadLedger(epicDir);
   if (!ledger.state) { fail(`no epic state at ${epicDir}`); process.exitCode = 1; return; }
-  log(`\n  ${c.bold(epic)}  ${c.dim(`currentStep: ${ledger.state.currentStep}`)}`);
+  const solo = isSolo(loadHub(root).hub);
+  log(`\n  ${c.bold(epic)}  ${c.dim(`currentStep: ${ledger.state.currentStep}${solo ? ' — solo mode (approval waived; merge still required)' : ''}`)}`);
   for (const s of ledger.state.steps.filter((x) => x.type === 'review+approve')) {
     const cur = artifactHash(epicDir, s.artifact);
     const live = ledger.approvals.filter((a) => a.step === s.id && a.status === 'approved' && !(a.artifactHash && cur && a.artifactHash !== cur));

package/cli/lib.mjs

@@ -30,6 +30,9 @@ export const info = (s) => log(`  ${c.dim('•')} ${s}`);
 export const warn = (s) => log(`  ${c.yellow('!')} ${s}`);
 export const fail = (s) => log(`  ${c.red('✗')} ${s}`);
 export const hand = (s) => log(`  ${c.yellow('→')} ${s}`);
+// Dimmed, indented guidance under a step — what it does / why / what to enter / what skipping means.
+// Accepts a string or an array of lines so a knowledgeable user can skim past it.
+export const guide = (lines) => { for (const l of (Array.isArray(lines) ? lines : [lines])) log(`    ${c.dim(l)}`); };
 
 // ---- prompts ------------------------------------------------------------
 let rl;

package/cli/next.mjs

@@ -0,0 +1,123 @@
+// `yad next` — the unified next-step driver. Read-only: it never writes state or acts. It reads the
+// file ledger and prints the ONE concrete, copy-pasteable next action (and a one-line why), so a user
+// never has to remember which of the 30 skills / gate commands comes next. "Guide, don't act" — the
+// front half still never auto-advances.
+//
+//   yad next                  general orientation across the whole project
+//   yad next <epic>           the single next action for one epic
+//   yad next <epic> --check <step>   exit 0 if <step> is runnable now, else 1 (the precondition guard)
+//   yad next --all            every active epic's next action at once
+import fs from 'node:fs';
+import path from 'node:path';
+import { c, log, ok, info, warn, hand, fail, readJSON, exists } from './lib.mjs';
+import { PROJECT_FILES } from './manifest.mjs';
+import { epicRoot, loadLedger, nextAction, preconditionsMet, isValidEpicId } from './epic-state.mjs';
+
+// Is solo mode on? Persisted in hub.json by setup (Phase C/D); default false. Read defensively so a
+// missing/old hub.json never breaks the driver.
+function isSolo(root) {
+  const hub = readJSON(path.join(root, PROJECT_FILES.hubConfig), null);
+  return !!(hub && (hub.solo === true || hub.review_gate?.solo === true));
+}
+// The setup profile recorded by `yad setup` (codebase / repo_layout / team_size), or null.
+const profileOf = (root) => readJSON(path.join(root, PROJECT_FILES.hubConfig), null)?.profile || null;
+// Has `yad setup` run here? True once the version stamp or hub config exists.
+const isSetUp = (root) => exists(path.join(root, PROJECT_FILES.version)) || exists(path.join(root, PROJECT_FILES.hubConfig));
+
+// Every epic that has a state ledger, in directory order.
+function listEpics(root) {
+  const dir = path.join(root, 'epics');
+  if (!exists(dir)) return [];
+  return fs.readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && isValidEpicId(e.name))
+    .map((e) => e.name)
+    .filter((id) => exists(path.join(dir, id, '.sdlc', 'state.json')))
+    .sort();
+}
+
+// A short, copy-pasteable line for one action — the `▸` line a user can act on directly.
+function actionLine(a, { solo } = {}) {
+  switch (a.kind) {
+    case 'new':
+      return `invoke the ${c.bold(a.skill)} skill ${c.dim('(author the epic)')}`;
+    case 'author':
+      return `invoke the ${c.bold(a.skill || ('yad-' + a.step))} skill ${c.dim(`(author ${a.artifact})`)}`;
+    case 'review-open':
+    case 'review-sync':
+      return `${c.bold(a.command)}${solo ? c.dim('   (solo: no approval needed — just merge your own PR)') : ''}`;
+    case 'build':
+      return `${c.bold('yad-run')} ${c.dim('(or per story: yad-spec → yad-implement → yad ship → yad-engineer-review)')}`;
+    default:
+      return c.dim('nothing to do');
+  }
+}
+
+// Full, friendly printout for a single epic.
+function printAction(a, { solo } = {}) {
+  log(`\n  ${c.bold(a.epicId || '(epic)')} ${c.dim(`— ${a.why}`)}`);
+  hand(actionLine(a, { solo }));
+  if (a.kind === 'review-sync') info(c.dim(`unresolved comments? ${c.bold(`yad gate comments ${a.epicId} ${a.artifact}`)}`));
+  if (a.parallel) hand(`parallel track: invoke the ${c.bold(a.parallel.skill)} skill ${c.dim(`(author ${a.parallel.artifact})`)}`);
+}
+
+// `yad next` with no epic: orient across the whole project, always ending on ONE thing to do.
+function generalNext(root, { all } = {}) {
+  if (!isSetUp(root)) {
+    log(`\n  ${c.bold('Project not set up yet.')}`);
+    hand(`run ${c.bold('yad setup')} ${c.dim('(then come back to `yad next`)')}`);
+    return;
+  }
+  const epics = listEpics(root);
+  if (!epics.length) {
+    const brownfield = profileOf(root)?.codebase === 'brownfield';
+    log(`\n  ${c.bold('Set up — no epics yet.')}`);
+    if (brownfield) hand(`capture what already exists first: invoke the ${c.bold('yad-backfill')} skill`);
+    hand(`start your first epic: invoke the ${c.bold('yad-epic')} skill`);
+    return;
+  }
+  const solo = isSolo(root);
+  const actions = epics.map((id) => nextAction(loadLedger(epicRoot(root, id)), { epic: id }));
+
+  if (epics.length === 1 || all) {
+    for (const a of actions) printAction(a, { solo });
+    return;
+  }
+  // Several epics — list each with a one-liner, then point at the per-epic / --all views.
+  log(`\n  ${c.bold(`${epics.length} epics`)} ${c.dim('— next action each:')}`);
+  for (const a of actions) log(`    ${c.cyan(a.epicId)}  ${actionLine(a, { solo })}`);
+  info(c.dim(`detail: ${c.bold('yad next <epic>')}  •  all at once: ${c.bold('yad next --all')}`));
+}
+
+// `yad next <epic> --check <step>`: the precondition guard. Exit 0 if runnable now, 1 otherwise.
+function checkPrecondition(root, epic, stepId) {
+  const ledger = loadLedger(epicRoot(root, epic));
+  const res = preconditionsMet(ledger.state, stepId);
+  if (res.ok) {
+    ok(`${epic}: ${stepId} is ready to run`);
+    return;
+  }
+  fail(`${epic}: ${stepId} is blocked — ${res.reason}`);
+  hand(`see what to do now: ${c.bold(`yad next ${epic}`)}`);
+  process.exitCode = 1;
+}
+
+// Entry point for the `next` command: route to the precondition check, a single epic's action, or the
+// project-wide general view. Validates the epic id first.
+export async function runNext(root, { epic, check, all } = {}) {
+  if (epic && !isValidEpicId(epic)) {
+    fail(`invalid epic id: ${epic} (expected EP-<slug>, [a-z0-9-] only)`);
+    process.exitCode = 1;
+    return;
+  }
+  if (epic && check) return checkPrecondition(root, epic, check);
+  if (!epic) return generalNext(root, { all });
+
+  const epicDir = epicRoot(root, epic);
+  if (!exists(path.join(epicDir, '.sdlc', 'state.json'))) {
+    warn(`no epic state at ${epicDir}/.sdlc/state.json`);
+    hand(`is the id right? list project status with ${c.bold('yad next')}`);
+    process.exitCode = 1;
+    return;
+  }
+  printAction(nextAction(loadLedger(epicDir), { epic }), { solo: isSolo(root) });
+}

package/cli/repo.mjs

@@ -13,11 +13,14 @@ function load(root) {
   return { regPath, registry: readJSON(regPath, { repos: [] }) };
 }
 
-// HEAD != syncedHead => stale (config.yaml code_context.staleness: head-sha).
+// HEAD != syncedHead => stale (config.yaml code_context.staleness: head-sha). A repo that has a HEAD but
+// no syncedHead was registered without a pack (the greenfield path) — it needs an initial pack, which is
+// also a "run `yad repo refresh`" state, kept distinct from HEAD-moved staleness.
 function staleness(root, repo) {
   const head = gitHead(path.resolve(root, repo.path));
+  const neverPacked = !!head && !repo.syncedHead;
   const stale = head && repo.syncedHead && head !== repo.syncedHead;
-  return { head, stale: !!stale, unknown: !head };
+  return { head, stale: !!stale, unknown: !head, neverPacked };
 }
 
 // ---- git helpers for `sync` (local-user auth only — never embed credentials) ----
@@ -40,9 +43,10 @@ export async function runRepo(root, { action = 'list', name, today } = {}) {
     log(c.bold('\nconnected repos'));
     let staleCount = 0;
     for (const repo of registry.repos) {
-      const { stale, unknown } = staleness(root, repo);
+      const { stale, unknown, neverPacked } = staleness(root, repo);
       if (unknown) { warn(`${repo.name} ${c.dim(`(${repo.path})`)} — HEAD unreadable`); continue; }
-      if (stale) { staleCount++; warn(`${repo.name} ${c.dim(`(${repo.path})`)} — ${c.yellow('stale')} (HEAD moved since last pack)`); }
+      if (neverPacked) { staleCount++; warn(`${repo.name} ${c.dim(`(${repo.path})`)} — ${c.yellow('no code-context pack yet')} (registered without one)`); }
+      else if (stale) { staleCount++; warn(`${repo.name} ${c.dim(`(${repo.path})`)} — ${c.yellow('stale')} (HEAD moved since last pack)`); }
       else ok(`${repo.name} ${c.dim('— fresh')}`);
     }
     if (staleCount) hand(`refresh with \`yad repo refresh${registry.repos.length > 1 ? ' <name>' : ''}\` (or \`yad repo refresh\` for all)`);

package/cli/setup.mjs

@@ -3,7 +3,7 @@ import path from 'node:path';
 import fs from 'node:fs';
 import os from 'node:os';
 import {
-  c, log, step, ok, info, warn, hand, fail, ask, askYesNo, run, has,
+  c, log, step, guide, ok, info, warn, hand, fail, ask, askYesNo, run, has,
   exists, readJSON, writeJSON,
 } from './lib.mjs';
 import { VERSION, IDE_FOLDER_TARGETS, PROJECT_FILES, DESIGN_TOOLS, DESIGN_PRIMARY, TESTING_TOOLS, TESTING_PRIMARY, LEARNING_TOOLS, LEARNING_PRIMARY } from './manifest.mjs';
@@ -176,7 +176,7 @@ export function reconcileRepoRoles(root, name, repo, current = [], want = []) {
   ok(`    ${repo}: ${want.length ? want.join(', ') : 'cleared'}`);
 }
 
-export function registerRepo(root, registry, { name, rpath, platform, domain_owner = '', domain_owners = null, default_branch = 'main', today = null }) {
+export function registerRepo(root, registry, { name, rpath, platform, domain_owner = '', domain_owners = null, default_branch = 'main', today = null, pack = true }) {
   if (!insideRoot(root, rpath)) {
     warn(`${rpath} resolves outside the project root — skipped`);
     return null;
@@ -198,7 +198,10 @@ export function registerRepo(root, registry, { name, rpath, platform, domain_own
     name, path: rpath, git_url: (remote.ok && remote.stdout) || null, platform: plat,
     domain_owner: owners[0] || '', domain_owners: owners, default_branch,
     connectedAt: today, lastSyncedAt: today,
-    syncedHead: head,
+    // Only claim a synced HEAD when a pack is actually produced. The greenfield path skips packing
+    // (pack:false), so leave syncedHead null — the repo then reads as "needs an initial pack" in
+    // `yad repo list` / `yad doctor` instead of falsely "fresh".
+    syncedHead: pack ? head : null,
     contextPack: `.sdlc/code-context/${name}/pack.md`,
     codeMap: `.sdlc/code-context/${name}/code-map.md`,
     source: 'repomix',
@@ -305,13 +308,70 @@ function applyActions(actions, { force = false } = {}) {
   return changed;
 }
 
+// Step 0 — resolve the setup profile that branches the rest of the wizard. Flags pre-answer each
+// question (CI/scripts); an existing hub.json carries prior answers forward (idempotent re-run);
+// otherwise we prompt with a default. Pure of side effects — it only reads. Returns
+// { solo, team_size, codebase, repo_layout, configureTools }.
+export async function resolveProfile(root, opts = {}) {
+  const hub = readJSON(path.join(root, PROJECT_FILES.hubConfig), null);
+  const prev = (hub && hub.profile) || {};
+
+  // 1. Solo or team (+ size). --solo / --team <n> win; else carry hub.solo forward; else ask.
+  let solo, team_size;
+  if (opts.solo) { solo = true; team_size = 1; }
+  else if (opts.team != null) { team_size = Math.max(1, parseInt(opts.team, 10) || 1); solo = team_size <= 1; }
+  else if (typeof hub?.solo === 'boolean') { solo = hub.solo; team_size = prev.team_size ?? (solo ? 1 : 2); }
+  else {
+    // Default from any existing roster: a hub already carrying reviewers is a team; otherwise solo.
+    const rosterN = Array.isArray(hub?.roster) ? hub.roster.length : 0;
+    solo = !(await ask('Solo or team?', rosterN > 1 ? 'team' : 'solo')).toLowerCase().startsWith('t');
+    team_size = solo ? 1 : Math.max(2, parseInt(await ask('  how many team members?', String(rosterN || 2)), 10) || 2);
+  }
+
+  // 2. Greenfield (new code) or brownfield (existing code).
+  let codebase;
+  if (opts.greenfield) codebase = 'greenfield';
+  else if (opts.brownfield) codebase = 'brownfield';
+  else if (prev.codebase) codebase = prev.codebase;
+  else codebase = (await ask('Greenfield (new code) or brownfield (existing code)?', 'greenfield')).toLowerCase().startsWith('b') ? 'brownfield' : 'greenfield';
+
+  // 3. Monorepo (one repo) or separate repos.
+  let repo_layout;
+  if (opts.monorepo) repo_layout = 'monorepo';
+  else if (opts.separate) repo_layout = 'separate';
+  else if (prev.repo_layout) repo_layout = prev.repo_layout;
+  else repo_layout = (await ask('Monorepo (one repo) or separate repos?', 'monorepo')).toLowerCase().startsWith('s') ? 'separate' : 'monorepo';
+
+  // 4. Configure the optional tools now, or defer (records them as none, connect later).
+  const configureTools = opts.tools === true ? true
+    : process.env.SDLC_NONINTERACTIVE ? false
+      : await askYesNo('Configure design/testing/learning tools now? (else connect them later)', false);
+
+  return { solo, team_size, codebase, repo_layout, configureTools };
+}
+
+// The guided, idempotent first-run wizard: a Step 0 profile interview (resolveProfile) that branches
+// the remaining steps — install, hub + roster, optional tools, repos, wiring — and persists the profile.
 export async function runSetup(root, opts = {}) {
-  const total = 10;
   log(c.bold(`\nSDLC Workflow setup  ${c.dim('v' + VERSION)}`));
   log(c.dim(`target: ${root}`));
 
-  // 1. Preflight
-  step(1, total, 'Preflight');
+  // 0. Profile interview — branch the wizard to the user's situation (solo/team, code, repo layout).
+  const { solo, team_size, codebase, repo_layout, configureTools } = await resolveProfile(root, opts);
+  // Steps: interview, preflight, install, hub, tools (1 if deferred else 3), repos, wire, coderabbit, done.
+  const total = 8 + (configureTools ? 3 : 1);
+  let _n = 0;
+  const S = (title) => step(++_n, total, title);
+
+  S('Profile');
+  guide([
+    'How you answer here shapes the rest of setup — fewer prompts, the right path.',
+    `solo: ${solo ? 'yes — you review by merging your own PR (approval waived)' : `no — team of ${team_size}`}`,
+    `code: ${codebase}  •  repos: ${repo_layout}  •  optional tools: ${configureTools ? 'configure now' : 'deferred (connect later)'}`,
+  ]);
+
+  // Preflight
+  S('Preflight');
   if (!exists(path.join(root, '.git'))) {
     if (await askYesNo('Not a git repo. Run `git init` here?', true)) {
       run('git', ['init'], { cwd: root });
@@ -321,8 +381,12 @@ export async function runSetup(root, opts = {}) {
   for (const tool of ['git', 'node']) has(tool) ? ok(`${tool} present`) : warn(`${tool} not found on PATH`);
   if (!has('npx')) warn('npx not found — repomix packing will be skipped');
 
-  // 2. Install the module
-  step(2, total, 'Install the module (skills + _bmad registration)');
+  // Install the module
+  S('Install the module (skills + _bmad registration)');
+  guide([
+    'Copies the yad-* skills into your AI tool(s) so they appear in Claude Code / agents / opencode.',
+    'Enter the IDE folders to install into, comma-separated; default = whatever is already present.',
+  ]);
   let ideTargets = opts.ideTargets;
   if (!ideTargets) {
     const present = ALL_IDES.filter((d) => exists(path.join(root, d)));
@@ -352,8 +416,18 @@ export async function runSetup(root, opts = {}) {
     }
   }
 
-  // 3. Detect hub platform + roster
-  step(3, total, 'Hub platform & reviewer roster');
+  // Detect hub platform + roster
+  S(solo ? 'Hub platform (solo — no roster)' : 'Hub platform & reviewer roster');
+  guide(solo
+    ? [
+      'Your hub is this repo on GitHub/GitLab (or none for a file-only gate).',
+      'Solo: no roster needed — you review by merging your own PR (approval waived).',
+    ]
+    : [
+      'Your hub is this repo on GitHub/GitLab; reviewers approve artifacts there.',
+      `Add your ${team_size}-person roster: platform login → yad name → hub role (owner/reviewer).`,
+      'An owner + 1 reviewer is required to pass a gate; skip now and add later with `yad roster add`.',
+    ]);
   const hubPath = path.join(root, PROJECT_FILES.hubConfig);
   if (exists(hubPath) && !(await askYesNo('hub.json exists — reconfigure?', false))) {
     info('keeping existing .sdlc/hub.json');
@@ -367,7 +441,8 @@ export async function runSetup(root, opts = {}) {
       platform = 'none';
     }
     const roster = [];
-    if (await askYesNo('Add reviewers to the roster now?', true)) {
+    // Solo mode needs no roster — the lone developer is owner and reviewer-by-merge.
+    if (!solo && await askYesNo('Add reviewers to the roster now?', true)) {
       for (;;) {
         const login = await ask('  reviewer platform login (blank to finish)', '');
         if (!login) break;
@@ -392,68 +467,113 @@ export async function runSetup(root, opts = {}) {
     // `bridge_enabled` is the canonical flag (hub-config schema); keep the legacy `bridge` spelling
     // for anything that still reads it.
     const enabled = platform !== 'none';
-    writeJSON(hubPath, { platform: enabled ? platform : null, bridge_enabled: enabled, bridge: enabled, default_branch, roster });
-    ok(`wrote ${PROJECT_FILES.hubConfig} (${roster.length} reviewer(s))`);
+    writeJSON(hubPath, { platform: enabled ? platform : null, bridge_enabled: enabled, bridge: enabled, default_branch, roster, solo, profile: { codebase, repo_layout, team_size } });
+    ok(`wrote ${PROJECT_FILES.hubConfig} (${roster.length} reviewer(s)${solo ? ', solo mode' : ''})`);
   }
-
-  // 4. Connect a design tool (Figma-first, pluggable; the UI step materializes the design here)
-  step(4, total, 'Connect a design tool (Figma / pencil / none)');
-  const designPath = path.join(root, PROJECT_FILES.designConfig);
-  if (exists(designPath) && !(await askYesNo('design.json exists — reconfigure?', false))) {
-    info('keeping existing .sdlc/design.json');
-  } else {
-    let tool = (await ask(`Design tool (${DESIGN_TOOLS.join('/')}/none)`, DESIGN_PRIMARY)).toLowerCase();
-    if (![...DESIGN_TOOLS, 'none'].includes(tool)) {
-      warn(`unknown design tool '${tool}' — using ${DESIGN_PRIMARY}`);
-      tool = DESIGN_PRIMARY;
+  // Persist the profile + solo flag even on the "keeping existing" path, so re-running setup with new
+  // flags (e.g. `yad setup --solo`) updates the mode without a full reconfigure. Merge, never clobber.
+  if (exists(hubPath)) {
+    const cur = readJSON(hubPath, {}) || {};
+    if (cur.solo !== solo || JSON.stringify(cur.profile || {}) !== JSON.stringify({ codebase, repo_layout, team_size })) {
+      writeJSON(hubPath, { ...cur, solo, profile: { codebase, repo_layout, team_size } });
+      info(`recorded profile: ${solo ? 'solo' : `team(${team_size})`}, ${codebase}, ${repo_layout}`);
     }
-    const project_url = tool === 'none' ? null : (await ask('  project/file URL (blank to set later)', '')) || null;
-    registerDesign(root, { tool, project_url, today: opts.today ?? null });
-    ok(tool === 'none'
-      ? `wrote ${PROJECT_FILES.designConfig} (markdown-only)`
-      : `wrote ${PROJECT_FILES.designConfig} (${tool})`);
   }
 
-  // 5. Connect a testing tool (Playwright-first, pluggable; the test-cases step implements automation here)
-  step(5, total, 'Connect a testing tool (playwright / cypress / pytest / none)');
+  // Optional tools (design / testing / learning). Paths are declared here so the final summary can
+  // read them whether or not we configured the tools this run.
+  const designPath = path.join(root, PROJECT_FILES.designConfig);
   const testingPath = path.join(root, PROJECT_FILES.testingConfig);
-  if (exists(testingPath) && !(await askYesNo('testing.json exists — reconfigure?', false))) {
-    info('keeping existing .sdlc/testing.json');
-  } else {
-    let tool = (await ask(`Testing tool (${TESTING_TOOLS.join('/')}/none)`, TESTING_PRIMARY)).toLowerCase();
-    if (![...TESTING_TOOLS, 'none'].includes(tool)) {
-      warn(`unknown testing tool '${tool}' — using ${TESTING_PRIMARY}`);
-      tool = TESTING_PRIMARY;
+  const learningPath = path.join(root, PROJECT_FILES.learningConfig);
+  if (configureTools) {
+    // Connect a design tool (Figma-first, pluggable; the UI step materializes the design here)
+    S('Connect a design tool (Figma / pencil / none)');
+    guide([
+      'Where yad-ui materializes real screens. figma (confirm the MCP later) or none for markdown-only.',
+      'Skipping is safe — the UI step degrades to ui-design.md.',
+    ]);
+    if (exists(designPath) && !(await askYesNo('design.json exists — reconfigure?', false))) {
+      info('keeping existing .sdlc/design.json');
+    } else {
+      let tool = (await ask(`Design tool (${DESIGN_TOOLS.join('/')}/none)`, DESIGN_PRIMARY)).toLowerCase();
+      if (![...DESIGN_TOOLS, 'none'].includes(tool)) {
+        warn(`unknown design tool '${tool}' — using ${DESIGN_PRIMARY}`);
+        tool = DESIGN_PRIMARY;
+      }
+      const project_url = tool === 'none' ? null : (await ask('  project/file URL (blank to set later)', '')) || null;
+      registerDesign(root, { tool, project_url, today: opts.today ?? null });
+      ok(tool === 'none'
+        ? `wrote ${PROJECT_FILES.designConfig} (markdown-only)`
+        : `wrote ${PROJECT_FILES.designConfig} (${tool})`);
     }
-    const project_url = tool === 'none' ? null : (await ask('  project/config reference (blank to set later)', '')) || null;
-    registerTesting(root, { tool, project_url, today: opts.today ?? null });
-    ok(tool === 'none'
-      ? `wrote ${PROJECT_FILES.testingConfig} (artifacts-only)`
-      : `wrote ${PROJECT_FILES.testingConfig} (${tool})`);
-  }
 
-  // 6. Connect a learning tool (DeepTutor-first, pluggable; the learning layer tutors team members here)
-  step(6, total, 'Connect a learning tool (deeptutor / none)');
-  const learningPath = path.join(root, PROJECT_FILES.learningConfig);
-  if (exists(learningPath) && !(await askYesNo('learning.json exists — reconfigure?', false))) {
-    info('keeping existing .sdlc/learning.json');
-  } else {
-    let tool = (await ask(`Learning tool (${LEARNING_TOOLS.join('/')}/none)`, LEARNING_PRIMARY)).toLowerCase();
-    if (![...LEARNING_TOOLS, 'none'].includes(tool)) {
-      warn(`unknown learning tool '${tool}' — using ${LEARNING_PRIMARY}`);
-      tool = LEARNING_PRIMARY;
+    // Connect a testing tool (Playwright-first, pluggable; the test-cases step implements automation here)
+    S('Connect a testing tool (playwright / cypress / pytest / none)');
+    guide([
+      'Where yad-test-cases generates automation. playwright/cypress/pytest, or none for artifacts-only.',
+      'Skipping is safe — test-cases authors test-cases.md only.',
+    ]);
+    if (exists(testingPath) && !(await askYesNo('testing.json exists — reconfigure?', false))) {
+      info('keeping existing .sdlc/testing.json');
+    } else {
+      let tool = (await ask(`Testing tool (${TESTING_TOOLS.join('/')}/none)`, TESTING_PRIMARY)).toLowerCase();
+      if (![...TESTING_TOOLS, 'none'].includes(tool)) {
+        warn(`unknown testing tool '${tool}' — using ${TESTING_PRIMARY}`);
+        tool = TESTING_PRIMARY;
+      }
+      const project_url = tool === 'none' ? null : (await ask('  project/config reference (blank to set later)', '')) || null;
+      registerTesting(root, { tool, project_url, today: opts.today ?? null });
+      ok(tool === 'none'
+        ? `wrote ${PROJECT_FILES.testingConfig} (artifacts-only)`
+        : `wrote ${PROJECT_FILES.testingConfig} (${tool})`);
+    }
+
+    // Connect a learning tool (DeepTutor-first, pluggable; the learning layer tutors team members here)
+    S('Connect a learning tool (deeptutor / none)');
+    guide([
+      'Lets any team member invoke yad-learn to be tutored in-context. deeptutor (a CLI), or none.',
+      'Skipping is safe — yad-learn tutors via the harness model (harness-native).',
+    ]);
+    if (exists(learningPath) && !(await askYesNo('learning.json exists — reconfigure?', false))) {
+      info('keeping existing .sdlc/learning.json');
+    } else {
+      let tool = (await ask(`Learning tool (${LEARNING_TOOLS.join('/')}/none)`, LEARNING_PRIMARY)).toLowerCase();
+      if (![...LEARNING_TOOLS, 'none'].includes(tool)) {
+        warn(`unknown learning tool '${tool}' — using ${LEARNING_PRIMARY}`);
+        tool = LEARNING_PRIMARY;
+      }
+      registerLearning(root, { tool, today: opts.today ?? null });
+      ok(tool === 'none'
+        ? `wrote ${PROJECT_FILES.learningConfig} (harness-native)`
+        : `wrote ${PROJECT_FILES.learningConfig} (${tool})`);
     }
-    registerLearning(root, { tool, today: opts.today ?? null });
-    ok(tool === 'none'
-      ? `wrote ${PROJECT_FILES.learningConfig} (harness-native)`
-      : `wrote ${PROJECT_FILES.learningConfig} (${tool})`);
+  } else {
+    // Deferred: record any not-yet-present tool as none (degrades gracefully). Existing connections kept.
+    S('Optional tools (design / testing / learning) — deferred');
+    guide(['Recorded as none; connect any later with the yad-connect-* skills. Existing connections are kept.']);
+    if (!exists(designPath)) registerDesign(root, { tool: 'none', project_url: null, today: opts.today ?? null });
+    if (!exists(testingPath)) registerTesting(root, { tool: 'none', project_url: null, today: opts.today ?? null });
+    if (!exists(learningPath)) registerLearning(root, { tool: 'none', today: opts.today ?? null });
+    info('design / testing / learning recorded as none (connect later)');
   }
 
-  // 7. Connect code repos
-  step(7, total, 'Connect code repos');
+  // Connect code repos
+  S(repo_layout === 'monorepo' ? 'Connect your code repo (monorepo)' : 'Connect code repos');
+  guide(repo_layout === 'monorepo'
+    ? [
+      'One repo holds all the code; the contract lives in the hub and stories tag this single repo.',
+      codebase === 'greenfield' ? 'Greenfield: no code yet — the repomix code-pack step is skipped.' : 'Brownfield: the repo is packed so the front phases see what already exists.',
+    ]
+    : [
+      'Register each code repo the feature touches; stories get tagged with the repos that implement them.',
+      'Per repo: name → path (inside this project) → platform → domain owner(s).',
+      codebase === 'greenfield' ? 'Greenfield: no code yet — the repomix code-pack step is skipped.' : 'Brownfield: each repo is packed so the front phases see what already exists.',
+    ]);
   const regPath = path.join(root, PROJECT_FILES.reposRegistry);
   const registry = readJSON(regPath, { repos: [] });
   const known = new Set(registry.repos.map((r) => r.name));
+  const greenfield = codebase === 'greenfield';
+  const mono = repo_layout === 'monorepo';
   if (await askYesNo(`Connect a code repo? ${c.dim(`(${registry.repos.length} already registered)`)}`, registry.repos.length === 0)) {
     for (;;) {
       const name = await ask('  repo name (blank to finish)', '');
@@ -463,26 +583,28 @@ export async function runSetup(root, opts = {}) {
       if (!insideRoot(root, rpath)) { warn(`${rpath} resolves outside the project root — skipped`); continue; }
       const detected = run('git', ['remote', 'get-url', 'origin'], { cwd: path.resolve(root, rpath) });
       const platform = (await ask('    platform (github/gitlab)', detectPlatform(detected.ok ? detected.stdout : '') || 'github')).toLowerCase();
-      // A repo can have one or more domain owners; reviewers/owners can also be scoped to it. Names
-      // refer to roster `name`s; each grant is written into that person's per-scope roles map.
-      const domain_owners = parseList(await ask('    domain owner(s) (yad names, space-separated)', ''));
-      const repoReviewers = parseList(await ask('    repo reviewer(s) (yad names, space-separated; blank to skip)', ''));
-      const repoOwners = parseList(await ask('    repo owner(s) (yad names, space-separated; blank to skip)', ''));
+      // Domain owners route the per-repo review. Solo (no roster) and monorepo (one repo = one owner)
+      // skip these prompts — there is no second person to route to.
+      const domain_owners = solo || mono ? [] : parseList(await ask('    domain owner(s) (yad names, space-separated)', ''));
+      const repoReviewers = solo || mono ? [] : parseList(await ask('    repo reviewer(s) (yad names, space-separated; blank to skip)', ''));
+      const repoOwners = solo || mono ? [] : parseList(await ask('    repo owner(s) (yad names, space-separated; blank to skip)', ''));
       const default_branch = await ask('    default branch', 'main');
-      const repo = registerRepo(root, registry, { name, rpath, platform, domain_owners, default_branch, today: opts.today ?? null });
+      const repo = registerRepo(root, registry, { name, rpath, platform, domain_owners, default_branch, today: opts.today ?? null, pack: !greenfield });
       if (!repo) continue;
       addRepoRoles(root, name, { 'domain-owner': domain_owners, reviewer: repoReviewers, owner: repoOwners });
       known.add(name);
       ok(`registered ${name}`);
-      packRepo(root, repo);
+      if (greenfield) info(`${name}: greenfield — skipped repomix pack (run \`yad repo refresh ${name}\` once it has code)`);
+      else packRepo(root, repo);
+      if (mono) { info('monorepo — one repo connected; stop here'); break; }
     }
   }
 
-  // 7b. Assign/update roles for ALREADY-connected repos. The connect loop above only prompts for the
-  // repos you add now; this closes the gap so a member's domain-owner/reviewer/owner role on a repo
-  // connected in an earlier run can be set without reconnecting. Mirrors `yad roster` (repo-driven).
+  // Assign/update roles for ALREADY-connected repos. Skipped in solo mode (no roster). The connect loop
+  // above only prompts for repos you add now; this closes the gap so a member's role on a repo connected
+  // in an earlier run can be set without reconnecting. Mirrors `yad roster` (repo-driven).
   const hub7 = readJSON(hubPath, null);
-  if (registry.repos.length && hub7 && Array.isArray(hub7.roster) && hub7.roster.length
+  if (!solo && registry.repos.length && hub7 && Array.isArray(hub7.roster) && hub7.roster.length
       && await askYesNo('Assign/update roles for connected repos?', false)) {
     for (const member of hub7.roster) {
       if (!(await askYesNo(`  edit ${member.name}'s repo roles?`, false))) continue;
@@ -496,8 +618,9 @@ export async function runSetup(root, opts = {}) {
     }
   }
 
-  // 8. Wire each connected repo + the hub itself
-  step(8, total, 'Wire connected repos + the hub (CI gates, PR template, comment scaffold, gate-sync)');
+  // Wire each connected repo + the hub itself
+  S('Wire connected repos + the hub (CI gates, PR template, comment scaffold, gate-sync)');
+  guide(['Installs the CI safety gates, PR/MR template, and gate-sync — automatic, no input needed.']);
   if (registry.repos.length === 0) info('no repos to wire');
   for (const repo of registry.repos) {
     log(`  ${c.bold(repo.name)} ${c.dim(`(${repo.platform})`)}`);
@@ -516,8 +639,9 @@ export async function runSetup(root, opts = {}) {
   // author allowlists for the verified-commits gate (hub + every repo), from the roster emails
   applyActions(authorsActions(root, registry.repos), { force: true });
 
-  // 9. Optional CodeRabbit
-  step(9, total, 'AI review (CodeRabbit)');
+  // Optional CodeRabbit
+  S('AI review (CodeRabbit)');
+  guide(['Advisory AI first-pass on PRs — never the authority. Opt in per repo; safe to skip.']);
   for (const repo of registry.repos) {
     const cr = path.join(path.resolve(root, repo.path), '.coderabbit.yaml');
     if (exists(cr)) { info(`${repo.name}: .coderabbit.yaml present`); continue; }
@@ -527,13 +651,25 @@ export async function runSetup(root, opts = {}) {
     }
   }
 
-  // 10. Summary + version stamp
-  step(10, total, 'Done');
+  // Summary + version stamp
+  S('Done');
   writeJSON(path.join(root, PROJECT_FILES.version), { version: VERSION, ideTargets, updatedAt: opts.today ?? null });
   ok(`stamped ${PROJECT_FILES.version} (v${VERSION})`);
   log('');
-  log(c.bold('Next — AI-only steps (run in Claude Code):'));
-  hand('generate code-maps: run `yad-connect-repos` for each connected repo');
+  // Tailored fastest path to the first epic, by profile.
+  log(c.bold('Next:'));
+  if (codebase === 'brownfield' && registry.repos.length) {
+    hand('capture what already exists first: run `yad-backfill`, then your first epic with `yad-epic`');
+  } else {
+    hand('author your first epic: run `yad-epic`');
+  }
+  hand('your single next action, anytime: `yad next`');
+  if (!solo && !(readJSON(hubPath, null)?.roster || []).length) {
+    hand('add reviewers when ready: `yad roster add <login>` (an owner + 1 reviewer passes a gate)');
+  }
+  log('');
+  log(c.bold('Then — AI-only steps (run in Claude Code):'));
+  if (registry.repos.length) hand('generate code-maps: run `yad-connect-repos` for each connected repo');
   const design = readJSON(designPath, null);
   if (design && design.tool && design.tool !== 'none') {
     hand(`confirm the design tool: run \`yad-connect-design\` to detect the ${design.tool} MCP (or it degrades to markdown-only)`);
@@ -546,7 +682,6 @@ export async function runSetup(root, opts = {}) {
   if (learning && learning.tool && learning.tool !== 'none') {
     hand(`confirm the learning tool: run \`yad-connect-learning\` to detect the ${learning.tool} CLI (or it degrades to harness-native)`);
   }
-  hand('author your first epic: run `yad-epic`');
   log('');
   log(c.dim('Re-run anytime: `yad check` (report) / `yad check --fix` (reconcile).'));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yadflow",
-  "version": "2.13.0",
+  "version": "2.14.0",
   "description": "Yadflow — the gated, team, multi-repo SDLC: author → review → build with a PR-driven review gate and a zero-dependency `yad` CLI (setup, gate, commit, open-pr, ship, repo). A BMAD module + 30 yad-* skills.",
   "type": "module",
   "author": "AbdelRahman Nasr",

package/skills/sdlc/config.yaml

@@ -31,6 +31,14 @@ defaults:
 # Team review gate defaults (build plan §3 piece 2, §4).
 review_gate:
   default_reviewers: 1          # non-owner reviewers required (in addition to 1 owner) => owner + 1 reviewer
+  # Solo mode (a lone developer): a relaxed, opt-in safety guarantee, recorded per-project in
+  # .sdlc/hub.json (`solo: true`). On GitHub you CANNOT approve your own PR, so requiring an approval
+  # would deadlock a solo user. Solo waives the APPROVAL requirement only — the review PR/MR and its
+  # MERGE stay (CI still runs on the PR, and the merge is what advances the step). Net: the gate passes
+  # on `merged + all comment threads resolved`, no approval needed. NOT a default; team gates are
+  # unchanged. (Branch protection must not "require approvals", or the solo dev's own merge is blocked —
+  # `yad doctor` warns when it does.)
+  solo: false
   escalate_when: [contract, auth, payments]   # escalate to domain owners
   # PR-driven automation (the `yad gate` CLI). With a hub platform, the review rides the per-step
   # PR/MR: `yad gate sync` maps platform reviews/threads into the file ledger and the step

package/skills/yad-analysis/SKILL.md

@@ -26,9 +26,12 @@ engine (never typed by hand); front steps are locked to `human_approve`.
 ## On Activation
 
 ### Step 1 — Get the idea
-Ask the user for a one-line feature idea if not provided. If `.sdlc/state.json` already exists for the
-target epic, analysis was already seeded (or the epic is past it) — stop and point the user at
-`yad-status`. The entry point seeds state exactly once.
+Ask the user for a one-line feature idea if not provided.
+
+**Precondition gate (rail):** analysis is the optional first entry point and seeds state exactly once.
+If `.sdlc/state.json` already exists for the target epic, run `yad next EP-<slug> --check analysis`; if it
+exits non-zero, **STOP** and point the user at `yad next EP-<slug>` (the epic is past analysis). If it
+exits zero, resume analysis for that epic. When no `state.json` exists yet, proceed and seed state.
 
 ### Step 2 — Shape the idea (assist: analyst)
 Adopt the **analyst** lens (`bmad-agent-analyst`, Mary) to pressure-test the idea in depth: who is the

package/skills/yad-architecture/SKILL.md

@@ -23,9 +23,14 @@ shared cross-repo surface at charter altitude; front steps stay locked to `human
 ## On Activation
 
 ### Step 1 — Resolve the epic and check the gate
-Resolve the `EP-<slug>` (ask if not provided). Read `{project-root}/epics/EP-<slug>/.sdlc/state.json`.
-Only proceed when `currentStep == "architecture"` and that step's `status == "in_progress"` (the epic
-review must already have passed). If not, stop and point the user at `yad-status` / the gate.
+Resolve the `EP-<slug>` (ask if not provided).
+
+**Precondition gate (rail):** run `yad next EP-<slug> --check architecture` first. If it exits non-zero,
+**STOP** — surface the blocker it prints and point the user at `yad next EP-<slug>`. Do not author until
+it passes. (The check is the authoritative rail; the description below explains what it enforces.)
+
+This passes when `architecture` is the next runnable step per the state sequence — every prior step
+(through the epic review) is `done` and `architecture` is not already `done`.
 
 ### Step 1b — Open the authoring branch
 Open the architecture authoring branch `architecture/EP-<slug>` per the shared procedure

package/skills/yad-epic/SKILL.md

@@ -40,7 +40,10 @@ exists for the idea.
 
 Either mode runs Step 3b (branch), Step 4 (write the epic), and Step 6 (stop at the gate).
 
-If `state.json` exists but `currentStep != "epic"`, stop and point the user at `yad-status` / the gate.
+**Precondition gate (rail):** if `state.json` already exists (analysis-ran or re-entry), run
+`yad next EP-<slug> --check epic` — if it exits non-zero, **STOP** and surface the blocker, pointing the
+user at `yad next EP-<slug>`. When no `state.json` exists yet, this is the greenfield entry point — the
+check is not applicable, so proceed and seed state.
 
 ### Step 2 — Shape the idea (assist: analyst) — or read the analysis
 - **Analysis skipped:** ask the user for a one-line feature idea if not provided, then adopt the

package/skills/yad-stories/SKILL.md

@@ -24,9 +24,14 @@ There is **no `sm` agent** (Phase 0 Deviation 1): the `pm` lens breaks down the
 ## On Activation
 
 ### Step 1 — Resolve the epic and check the gate
-Resolve the `EP-<slug>` (ask if not provided). Read `.sdlc/state.json`. Only proceed when
-`currentStep == "stories"` and that step's `status == "in_progress"` (the UI review must already have
-passed). If not, stop and point the user at `yad-status` / the gate.
+Resolve the `EP-<slug>` (ask if not provided).
+
+**Precondition gate (rail):** run `yad next EP-<slug> --check stories` first. If it exits non-zero,
+**STOP** — surface the blocker it prints and point the user at `yad next EP-<slug>`. Do not author until
+it passes.
+
+This passes when `stories` is the next runnable step per the state sequence — every prior step
+(through the UI review) is `done` and `stories` is not already `done`.
 
 ### Step 1b — Open the authoring branch
 Open the stories authoring branch `stories/EP-<slug>` per the shared procedure

package/skills/yad-test-cases/SKILL.md

@@ -36,11 +36,16 @@ the Markdown artifact only — the testing tool is additive, exactly like the de
 ## On Activation
 
 ### Step 1 — Resolve the epic and check the track
-Resolve the `EP-<slug>` (ask if not provided). Read `.sdlc/state.json`. Only proceed when the
-**`test-cases` step's `status == "in_progress"`** — it opens when `stories-review` passes (the epic is
-already `ready-for-build` by then; `currentStep` stays there because this is a parallel track, so do
-**not** gate on `currentStep`). If `test-cases` is still `blocked`, the stories review has not passed —
-stop and point the user at `yad-status` / the gate.
+Resolve the `EP-<slug>` (ask if not provided).
+
+**Precondition gate (rail):** run `yad next EP-<slug> --check test-cases` first. If it exits non-zero,
+**STOP** — surface the blocker it prints and point the user at `yad next EP-<slug>`. Do not author until
+it passes. The check is track-aware: it keys off the `test-cases` step's predecessors, **not**
+`currentStep` (this is a parallel track — `currentStep` stays at `ready-for-build`).
+
+This passes once the `test-cases` step is runnable — its predecessor `stories-review` is `done` (so the
+step has opened to `in_progress`) and `test-cases` is not already `done`. While it is still `blocked`,
+the stories review has not passed.
 
 ### Step 1b — Open the authoring branch
 Open the test-cases authoring branch `test-cases/EP-<slug>` per the shared procedure

package/skills/yad-ui/SKILL.md

@@ -33,9 +33,14 @@ like Impeccable.
 ## On Activation
 
 ### Step 1 — Resolve the epic and check the gate
-Resolve the `EP-<slug>` (ask if not provided). Read `.sdlc/state.json`. Only proceed when
-`currentStep == "ui-design"` and that step's `status == "in_progress"` (the architecture review must
-already have passed). If not, stop and point the user at `yad-status` / the gate.
+Resolve the `EP-<slug>` (ask if not provided).
+
+**Precondition gate (rail):** run `yad next EP-<slug> --check ui-design` first. If it exits non-zero,
+**STOP** — surface the blocker it prints and point the user at `yad next EP-<slug>`. Do not author until
+it passes.
+
+This passes when `ui-design` is the next runnable step per the state sequence — every prior step
+(through the architecture review) is `done` and `ui-design` is not already `done`.
 
 ### Step 1b — Open the authoring branch
 Open the UI authoring branch `ui-design/EP-<slug>` per the shared procedure