solo-cto-agent 1.3.2 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## v1.4.0 (2026-04-19)
+
+**Theme**: End-to-end automation complete. Install is fully automatic; review → rework → visual → merge runs without human copy-paste; Telegram / Discord carry the full operational loop.
+
+### Highlights
+* **Natural-language work orders** — `solo-cto-agent do "..."` CLI + Telegram `/do` route a plain-English instruction to the right product repo as a labeled, spec-rich issue the existing worker pipeline picks up.
+* **3-round agent consensus** — `cross-reviewer.js` runs an A/B debate (R1 propose → R2 agree/disagree/add → R3 verdict) with early-exit on agreement; non-consensus after R3 still dispatches rework with a distinguishable reason.
+* **Before/After visual report** — new `visual-report.yml` + `visual-reporter.js` capture screenshots of the Vercel preview at the pre- and post-rework SHA, compose side-by-side PNGs, commit them to the orchestrator, post to PR + Telegram `sendMediaGroup`.
+* **Opt-in GitHub auto-merge** — PR with `auto-merge-when-ready` label is merged by GitHub the moment all required checks pass (native `enablePullRequestAutoMerge` mutation; branch protection respected).
+* **Unified dispatcher** — `solo-cto-pipeline.yml` is now the single product-repo dispatcher with 7-layer anti-loop guards. Legacy `cross-review-dispatch.yml` + `rework-dispatch.yml` deleted; concurrency guards added on orchestrator receivers.
+* **Full install automation** — `setup.sh` now creates the orchestrator repo on GitHub, pushes it, and sets the `TRACKED_REPOS` variable itself instead of printing copy-paste commands.
+* **Telegram CTO command surface** — `/status`, `/list`, `/rework`, `/approve`, `/do`, `/digest`, `/merge` (admin-gated). Every review / rework / report message includes inline buttons for ✅ Approve · ❌ Reject · 🔧 Rework · 🔀 Merge.
+* **Discord mirror** — set `DISCORD_WEBHOOK_URL` and visual-change screenshots / auto-diagnose reports mirror to Discord as file attachments.
+* **Repo auto-discovery** — `init --wizard` shells out to `gh api` and offers a multi-select of the user's repos; saved selection auto-fills `--repos` on every subsequent command.
+
+### Pipeline fixes
+* `review-request` dispatch no longer orphaned — solo-cto-pipeline now emits `cross-review` to match the existing orchestrator listener.
+* Anti-loop guards in solo-cto-pipeline extended to recognise new comment formats: `## 🔍 Consensus Review`, `## Visual Report — Before / After`, `[visual-report-skipped:…]`, circuit-breaker comments, auto-merge-enabled comments, `<!-- cross-reviewer:consensus -->` machine tag.
+* Claude model IDs unified to `claude-sonnet-4-6` across rework-agent, claude-reviewer, claude-worker (was mixed 4.0 / 4.6).
+* Hardcoded `seunghunbae-3svs` owner in `solo-cto-pipeline.yml` replaced with `{{GITHUB_OWNER}}` placeholder — every non-maintainer user was hitting silent dispatch failures.
+* OpenAI call in rework-agent was passing `system` as a top-level parameter (wrong shape); moved into `messages[]` as a system-role message.
+
+### New notification paths
+* **`pr-merge-notify.yml`** — fires on PR closed (merged or not); posts consolidated Telegram + Discord summary with rework round count.
+* **`combined-pr-with-uiux.yml` rewired** — now triggers on the real workflow name (`Visual Report (Before/After)`), posts the single "all agent checks passed" message exactly once per PR.
+* `visual-check.yml` fires on `workflow_run: Auto Rework on Review completed` → fresh preview screenshots after every rework.
+* `auto-diagnose.yml` fires on rework-auto **failure** → Telegram-attached JSON diagnostic.
+* Skip paths (`[visual-report-skipped:…]`) now notify Telegram/Discord too so silent failures aren't silent.
+
+### Docs + hygiene
+* README front section rewritten to describe the full pipeline (consensus, rework, visual, Telegram) instead of just dual-agent review.
+* New `docs/user-journey.md` — install → trigger → review → rework → visual → merge, with ASCII flow diagram, common scenarios, troubleshooting table.
+* `docs/hero-banner-prompt.md` (new) — regeneration prompt for the README hero image aligned with the expanded surface.
+* `.env.example` covers Discord / Vercel / Browserless / admin Telegram chat IDs.
+* PAT scope guidance expanded for classic vs fine-grained tokens.
+* `require.main === module` guards on `visual-check.js` + `auto-diagnose.js` so tests can import them without firing `main()`.
+* Audit report from 2026-04-19 published as a gist: https://gist.github.com/seunghunbae-3svs/4f3da08f149fdb2b2451b43751f6f35c
+
+### Merged PRs
+* #106 — vision batch (repo-discovery / consensus / visual-report / NL orders / Telegram CTO)
+* #107 — pipeline consolidation
+* #108 — docs sync with #106/#107
+* #109 — end-to-end loop closure (install automation, merge notifications, D1/D2 wiring, README)
+* (this release) — `require.main` guards + hero banner prompt + de-dupe combined-pr-with-uiux trigger
+
+---
+
 ## v1.3.0 (2026-04-17)
 
 **Theme**: Tier 3 deep integration features — plugin registry search, setup automation, type system enhancements.
@@ -121,6 +168,20 @@ non-interactive verify in CI, and tear it all down with one command.
 
 ## Unreleased
 
+* Merge pull request #109 from seunghunbae-3svs/claude/e2e-audit
+
+* Merge pull request #108 from seunghunbae-3svs/claude/docs-sync
+
+* Merge pull request #107 from seunghunbae-3svs/claude/pipeline-consolidation
+
+* Merge pull request #106 from seunghunbae-3svs/claude/vision-batch
+
+* Merge pull request #105 from seunghunbae-3svs/claude/friendly-black-efec58
+
+* docs: sharpen README intro — feature-first, install in 2 lines
+
+* chore: v1.3.2 — clean up README slop, sync versions, update metrics
+
 * ci: add VS Code extension auto-publish to release workflow
 
 * docs: add hero banner to README, update test badge to 996

package/README.md

@@ -4,46 +4,103 @@
 
 # solo-cto-agent
 
-**Dual-agent code review, secret detection, and circuit breakers for solo founders.**
+**The full CTO loop for solo founders — dual-agent review, multi-turn consensus, auto-rework, before/after visual reports, and a Telegram/Discord control surface.**
 
 [![npm](https://img.shields.io/npm/v/solo-cto-agent)](https://www.npmjs.com/package/solo-cto-agent)
 [![Test](https://img.shields.io/badge/tests-996%20passing-brightgreen)](https://github.com/seunghunbae-3svs/solo-cto-agent/actions/workflows/test.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
 
-> Stop babysitting your AI agent. `solo-cto-agent` adds circuit breakers for error loops, dual-agent code review, design quality gates, session memory, and deployment checklists — so you can focus on building instead of supervising.
+You push code. Two AI agents review it, debate for up to three rounds until they reach consensus, auto-push fixes for any blockers, shoot before/after screenshots of your Vercel preview, and ping your phone on Telegram with action buttons. When you tap ✅ Merge (or set the `auto-merge-when-ready` label), GitHub merges it once CI is green. You stay in the loop from your phone; you never touch YAML.
 
-**For solo founders, indie hackers, and small teams using Claude Cowork + OpenAI Codex.**
+```bash
+npm i -g solo-cto-agent
+solo-cto-agent init --wizard         # pick your repos, pick your tier
+solo-cto-agent do "fix the auth bug in tribo"   # natural-language work order
+# ...PR opens → review → rework → merge, all visible in Telegram.
+```
+
+**Surfaces**: CLI · [GitHub Action](action.yml) · [VS Code Extension](https://marketplace.visualstudio.com/items?itemName=seunghunbae-3svs.solo-cto-agent) · Telegram bot · optional Discord mirror.
 
 > **Languages**: English (primary) - [한국어 안내](#한국어-안내) below.
 
-## Quickstart (5 minutes)
+## Quickstart
 
 ```bash
-# 1. Install
+# 1. Install + wizard (wizard auto-discovers your repos via gh CLI,
+#    creates the orchestrator repo on GitHub, sets TRACKED_REPOS,
+#    and installs workflows on every product repo you pick.)
 npm install -g solo-cto-agent
-
-# 2. Initialize (recommended: choose mode during wizard)
 npx solo-cto-agent init --wizard
 
-# 3. Set your Anthropic API key (required for reviews)
-#    Get one at: https://console.anthropic.com/settings/keys
-export ANTHROPIC_API_KEY="sk-ant-..."
+# 2. Keys (all set in your shell, then copied to repo secrets by setup)
+export ANTHROPIC_API_KEY="sk-ant-..."     # required — Claude review + NL orders
+export OPENAI_API_KEY="sk-..."            # required for dual-agent / CTO tier
+export ORCHESTRATOR_PAT="ghp_..."         # required — cross-repo dispatch + write
+export TELEGRAM_BOT_TOKEN="..."           # optional — PR notifications + /commands
+export TELEGRAM_CHAT_ID="..."             # optional
+export DISCORD_WEBHOOK_URL="https://..."  # optional — mirror of Telegram output
+export VERCEL_TOKEN="..."                 # optional — before/after visual reports
 
-# 4. (Optional) Set OpenAI key for dual-review mode
-#    Get one at: https://platform.openai.com/api-keys
-export OPENAI_API_KEY="sk-..."
+# 3. Run setup-pipeline (reads saved wizard selection; no manual --repos needed)
+solo-cto-agent setup-pipeline --org <your-github-org>
 
-# 5. Verify everything is ready
-solo-cto-agent doctor --quick
+# 4. Verify
+solo-cto-agent doctor
 
-# 6. Run your first review (inside a git repo with staged changes)
-solo-cto-agent review
+# 5. Kick off a real work order
+solo-cto-agent do "add a monthly ARPU chart to the tribo admin dashboard"
+#   → LLM picks target repo, drafts a spec issue, labels agent-claude
+#   → claude worker opens a PR
+#   → cross-reviewer.js runs 3-round consensus
+#   → rework-agent.js pushes fixes if needed
+#   → visual-report.yml posts before/after screenshots
+#   → combined-pr-gate.yml sends "all checks passed" to Telegram
+#   → auto-merge-when-ready label makes GitHub merge on CI green
+#   → pr-merge-notify.yml sends final "✅ merged" to Telegram/Discord
 ```
 
-That is it. `doctor --quick` will tell you what is missing, where to get it, and the next command to run.
+Every step above ships end-to-end today. The `doctor` subcommand tells you anything missing with the exact command to run.
+
+### Telegram bot — the phone-first control surface
+
+After you set `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID`, the bot gives you:
+
+| Command | What it does |
+|---|---|
+| `/status [repo]` | Open, non-draft PRs + review state across tracked repos |
+| `/list [repo]` | Last 10 PRs, one-line summary each |
+| `/rework <pr>` | Force a rework cycle on an existing PR |
+| `/approve <pr>` | Approve the PR |
+| `/do "<instruction>"` | Natural-language work order (same as CLI `do`) |
+| `/digest` | Today's PR activity summary |
+| `/merge <pr>` | Immediate merge (admin-only: `TELEGRAM_ADMIN_CHAT_IDS`) |
+
+Every review / rework / visual-report message includes inline buttons — ✅ Approve · ❌ Reject · 🔧 Rework · 🔀 Merge. Tap to act without leaving Telegram.
 
-### Platform-specific setup
+If `DISCORD_WEBHOOK_URL` is set, visual-change screenshots and auto-diagnose reports mirror to Discord as attachments.
+
+### External services
+
+| Service | Used for | Required? | Setup |
+|---|---|---|---|
+| **GitHub** | orchestrator repo + product repo workflows | ✅ required | wizard auto-creates orchestrator repo via `gh repo create` |
+| **Anthropic** | Claude consensus review, NL orders, rework | ✅ required | `ANTHROPIC_API_KEY` env var |
+| **OpenAI** | Codex counter-review (dual-agent) | CTO tier | `OPENAI_API_KEY` env var |
+| **Vercel** | preview URLs for before/after visual-report | optional | `VERCEL_TOKEN` + `VERCEL_PROJECT_ID`. Works with **Netlify / Cloudflare Pages / Render / Railway previews** too if their `deployment_status` webhooks fire — the visual stage resolves the URL from SHA and shoots whichever host serves it. |
+| **Telegram** | notifications + CTO commands | optional | `/telegram wizard` command + bot token |
+| **Discord** | optional mirror of Telegram output | optional | `DISCORD_WEBHOOK_URL` on orchestrator secrets |
+| **Browserless** | alternate screenshot provider (skips Playwright install cost) | optional | `VISUAL_REVIEW_PROVIDER=browserless` + `BROWSERLESS_API_KEY` |
+
+### Compatibility
+
+- **Stack-agnostic.** The toolkit never touches your application code directly. Agents produce patches that land on your PR branch; your repo's existing CI / build tools verify them. Works with Next.js, Vite, Remix, SvelteKit, FastAPI, Rails — anything with a PR workflow.
+- **Hosting-agnostic.** Vercel is the default for the visual-report preview URL resolver, but any host that ships preview URLs tied to commit SHAs works. For hosts without that (plain Docker, bare-metal, self-hosted): set `VISUAL_REVIEW_PROVIDER=off` and the pipeline just skips the visual stage — everything else still runs.
+- **Database-agnostic.** The toolkit doesn't read or write your database. Postgres (Supabase / Neon / PlanetScale-Postgres), MySQL, SQLite, MongoDB — all fine. Agent workers DO see your schema files if they're in the repo (prisma/schema.prisma, supabase/schema.sql, etc.) so suggested fixes can be schema-aware.
+- **Docker.** If your product repo is dockerized, nothing changes — GitHub Actions runners handle the build per your existing Dockerfile. The agents commit to the PR branch, your CI rebuilds the container, the auto-merge gate waits on that CI.
+- **Windows / macOS / Linux** for the CLI. GitHub Actions runners are Linux for all automation paths.
+
+### Platform-specific CLI setup
 
 **macOS / Linux**
 
@@ -64,6 +121,8 @@ solo-cto-agent doctor
 If you choose `codex-main` during the wizard, also install:
 - GitHub CLI: [cli.github.com](https://cli.github.com/)
 - GitHub PAT for cross-repo dispatch: [github.com/settings/personal-access-tokens/new](https://github.com/settings/personal-access-tokens/new)
+  - **Classic PAT**: check `repo` + `workflow` scopes.
+  - **Fine-grained PAT**: grant `Contents: write`, `Issues: write`, `Pull requests: write`, `Actions: write` on every product repo listed in `setup-pipeline --repos`. The orchestrator pushes fix commits and posts comments on those repos on your behalf.
 
 If you choose `codex-main`, template drift audit is enabled by default:
 - local check: `solo-cto-agent template-audit`
@@ -259,18 +318,26 @@ solo-cto-agent/
 
 ## Three Axes: Tier / Agent / Mode
 
+At a glance:
+
+|          | Cowork (semi-auto) | Codex (full-auto)     |
+|----------|--------------------|-----------------------|
+| Builder  | local + manual review | CI dispatch + auto-fix |
+| CTO      | local + dual-agent cross-review | CI dispatch + dual + cross-review + scoring |
+
+Cowork runs in your terminal with you in the loop. Codex runs in CI and reworks itself until the PR passes.
+
 `solo-cto-agent` is configured across three independent axes. You choose each based on your workflow.
 
 | Axis | Decision | Options |
 |---|---|---|
-| Tier | Scope of capability | Maker / Builder / CTO |
+| Tier | Scope of capability | Builder / CTO |
 | Agent | Who reviews | Cowork (Claude) / Cowork + Codex |
 | Mode | Automation depth | Semi-auto (cowork-main) / Full-auto (codex-main) |
 
 Quick pick if you are unsure:
-- Start with Maker + Cowork + Semi-auto.
-- Move to Builder when you are shipping real features.
-- Move to CTO + Full-auto when you want always-on CI/CD and multi-agent routing.
+- Start with Builder + Cowork (single Claude agent, semi-auto, optional Telegram bot).
+- Move to CTO + Full-auto when you want dual-agent cross-review and always-on CI/CD across repos.
 
 ### Agents (summary)
 
@@ -307,15 +374,13 @@ Full-auto adds:
 ### Tiers (summary)
 
 **Not sure which tier? One question:**
-- Are you shipping code to production? → **Builder** (default, recommended for most users)
-- Only doing idea validation / reviews? → **Maker**
-- Running multi-repo CI/CD with full automation? → **CTO**
+- Solo dev shipping code with one Claude agent? → **Builder** (default, recommended for most users)
+- Want dual-agent cross-review (Claude + Codex) and multi-repo CI/CD? → **CTO**
 
-| Tier | Includes | Recommended for |
-|---|---|---|
-| Maker | spark + review + memory + craft | idea and validation loops |
-| Builder | Maker + build + ship | solo dev shipping |
-| CTO | Builder + orchestrate | multi-agent + routing |
+| Tier | Includes | Agents | Extras | Recommended for |
+|---|---|---|---|---|
+| Builder | spark + review + memory + craft + build + ship | solo Claude | optional Telegram bot for PR notify/approve | solo dev shipping |
+| CTO | Builder + orchestrate | Claude + Codex (dual-agent cross-review) | agent scoring, routing, decision queue, daily briefing | multi-agent CI/CD across repos |
 
 Details: `docs/tier-matrix.md`, `docs/tier-examples.md`, `docs/cto-policy.md`, `docs/cowork-main-install.md`, `docs/configuration.md`.
 

package/bin/cli.js

@@ -30,6 +30,8 @@ let telegramBot;
 try { telegramBot = require("./telegram-bot"); } catch (_) { telegramBot = null; }
 let selfEvolve;
 try { selfEvolve = require("./self-evolve"); } catch (_) { selfEvolve = null; }
+let repoDiscovery;
+try { repoDiscovery = require("./repo-discovery"); } catch (_) { repoDiscovery = null; }
 
 const ROOT = path.resolve(__dirname, "..");
 const DEFAULT_CATALOG = path.join(ROOT, "failure-catalog.json");
@@ -65,6 +67,8 @@ function printHelp() {
 Usage:
   solo-cto-agent init [--force] [--preset maker|builder|cto] [--wizard]
   solo-cto-agent setup-pipeline --org <github-org> [--tier builder|cto] [--repos <repo1,repo2,...>]
+  solo-cto-agent repos list [--org <github-org>]      # show/re-pick the saved repo selection
+  solo-cto-agent do "<instruction>" [--dry-run] [--repo owner/name] [--agent claude|codex]
   solo-cto-agent setup-repo <repo-path> --org <github-org> [--tier builder|cto]
   solo-cto-agent auto-setup                 # Install solo-cto-pipeline.yml to your repos (centralized)
   solo-cto-agent setup --central --org <owner> [--orchestrator <repo>] [--repos <r1,r2,...>] [--dry-run]
@@ -93,6 +97,8 @@ Usage:
 Commands:
   init              Install skills to ~/.claude/skills/, then run doctor to verify setup
   setup-pipeline    Full pipeline setup: create orchestrator repo + install workflows to product repos
+  repos list        Print current saved repo selection (from init wizard) and re-pick interactively
+  do                Natural-language work order: LLM parses intent → creates labeled issue → worker runs
   setup-repo        Install dual-agent workflows to a single product repo
   auto-setup        Install solo-cto-pipeline.yml (centralized thin workflow) to selected repos
   setup --central   Centralize cross-repo workflows (digest, bot-runner) to orchestrator repo
@@ -401,6 +407,82 @@ Style: {{YOUR_STYLE}}
   doctorCommand({ exitOnError: false, quick: true });
 }
 
+// ─── repos: show/re-pick saved selection ────────────────────
+
+async function reposCommand(args) {
+  if (!repoDiscovery) {
+    console.error("❌ repo-discovery module not available in this install.");
+    process.exit(1);
+  }
+  const sub = args[1] || "list";
+  if (sub !== "list") {
+    console.error(`Unknown repos subcommand: ${sub}`);
+    console.error("Usage: solo-cto-agent repos list [--org <github-org>]");
+    process.exit(1);
+  }
+
+  const orgIndex = args.indexOf("--org");
+  let org = orgIndex >= 0 ? args[orgIndex + 1] : null;
+
+  const saved = repoDiscovery.loadSelection();
+  if (saved) {
+    console.log(`Saved selection (${repoDiscovery.selectionPath()}):`);
+    console.log(`  org:     ${saved.org || "(user-scoped)"}`);
+    console.log(`  updated: ${saved.updatedAt || "—"}`);
+    console.log(`  repos:   ${saved.selected.length ? saved.selected.join(", ") : "(none)"}`);
+    if (!org && saved.org) org = saved.org;
+  } else {
+    console.log("No saved selection yet. Run `solo-cto-agent init --wizard` first, or re-pick below.");
+  }
+
+  // Non-TTY callers (CI) just get the print-out.
+  const { isTTY, createRl } = require("./prompt-utils");
+  const { ask } = require("./prompt-utils");
+  if (!isTTY()) {
+    console.log("\nℹ️  Non-interactive terminal — skipping re-pick prompt.");
+    return;
+  }
+
+  const rl = createRl();
+  try {
+    const again = await ask(rl, "\nRe-pick repos now?", "n");
+    if (!/^y(es)?$/i.test(again.trim())) {
+      rl.close();
+      return;
+    }
+
+    let repos = null;
+    try {
+      repos = repoDiscovery.fetchRepos({ org });
+    } catch (err) {
+      console.log(`⚠️  ${err.message}`);
+    }
+
+    if (repos == null) {
+      console.log("`gh` CLI not found. Install from https://cli.github.com/ then `gh auth login`.");
+      const manual = await ask(rl, "Paste repo slugs manually (comma-separated, or blank to cancel)", "");
+      const selected = manual.split(",").map((s) => s.trim()).filter(Boolean);
+      if (selected.length) {
+        const file = repoDiscovery.saveSelection({ org, selected, discovered: [] });
+        console.log(`✅ Saved ${selected.length} repo(s) to ${file}`);
+      } else {
+        console.log("No changes.");
+      }
+    } else if (repos.length === 0) {
+      console.log("No repositories returned from gh.");
+    } else {
+      const preselected = saved && Array.isArray(saved.selected) && saved.selected.length
+        ? saved.selected
+        : repoDiscovery.defaultPreselect(repos);
+      const selected = await repoDiscovery.pickReposInteractive(rl, ask, repos, preselected);
+      const file = repoDiscovery.saveSelection({ org, selected, discovered: repos });
+      console.log(`✅ Saved ${selected.length} repo(s) to ${file}`);
+    }
+  } finally {
+    rl.close();
+  }
+}
+
 // ─── setup-pipeline: Full Pipeline Deploy ───────────────────
 
 function setupPipelineCommand(tier, org, repos, orchName, force) {
@@ -2061,6 +2143,17 @@ async function main() {
     return false;
   }
 
+  if (cmd === "repos") {
+    await reposCommand(args);
+    return;
+  }
+
+  if (cmd === "do") {
+    const doModule = require("./do");
+    await doModule.main();
+    return;
+  }
+
   if (cmd === "setup-pipeline") {
     if (checkCoworkMainMode()) {
       console.log("ℹ️  Not needed in cowork-main mode. Use `review`, `knowledge`, and `sync` commands instead.");
@@ -2071,7 +2164,15 @@ async function main() {
     const orgIndex = args.indexOf("--org");
     const org = orgIndex >= 0 ? args[orgIndex + 1] : null;
     const reposIndex = args.indexOf("--repos");
-    const repos = reposIndex >= 0 ? args[reposIndex + 1] : null;
+    let repos = reposIndex >= 0 ? args[reposIndex + 1] : null;
+    // Fall back to the selection persisted by `init --wizard` / `repos list`.
+    if (!repos && repoDiscovery) {
+      const saved = repoDiscovery.loadSelection();
+      if (saved && Array.isArray(saved.selected) && saved.selected.length) {
+        repos = saved.selected.join(",");
+        console.log(`ℹ️  Using saved repo selection (${saved.selected.length} repos from ${repoDiscovery.selectionPath()}).`);
+      }
+    }
     const orchIndex = args.indexOf("--orchestrator-name");
     const orchName = orchIndex >= 0 ? args[orchIndex + 1] : null;
     setupPipelineCommand(tier, org, repos, orchName, force);
@@ -2136,7 +2237,14 @@ async function main() {
     const orgIndex = args.indexOf("--org");
     const org = orgIndex >= 0 ? args[orgIndex + 1] : null;
     const reposIndex = args.indexOf("--repos");
-    const repos = reposIndex >= 0 ? args[reposIndex + 1] : null;
+    let repos = reposIndex >= 0 ? args[reposIndex + 1] : null;
+    if (!repos && repoDiscovery) {
+      const saved = repoDiscovery.loadSelection();
+      if (saved && Array.isArray(saved.selected) && saved.selected.length) {
+        repos = saved.selected.join(",");
+        console.log(`ℹ️  Using saved repo selection (${saved.selected.length} repos).`);
+      }
+    }
     const orchIndex = args.indexOf("--orchestrator-name");
     const orchName = orchIndex >= 0 ? args[orchIndex + 1] : null;
     upgradeCommand(org, repos, orchName);
@@ -2147,7 +2255,14 @@ async function main() {
     const orgIndex = args.indexOf("--org");
     const org = orgIndex >= 0 ? args[orgIndex + 1] : null;
     const reposIndex = args.indexOf("--repos");
-    const repos = reposIndex >= 0 ? args[reposIndex + 1] : null;
+    let repos = reposIndex >= 0 ? args[reposIndex + 1] : null;
+    if (!repos && repoDiscovery) {
+      const saved = repoDiscovery.loadSelection();
+      if (saved && Array.isArray(saved.selected) && saved.selected.length) {
+        repos = saved.selected.join(",");
+        console.log(`ℹ️  Using saved repo selection (${saved.selected.length} repos).`);
+      }
+    }
     const orchIndex = args.indexOf("--orchestrator-name");
     const orchName = orchIndex >= 0 ? args[orchIndex + 1] : "dual-agent-orchestrator";
     const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN || process.env.ORCHESTRATOR_PAT;

package/bin/do.js

@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+
+/**
+ * do — natural-language work order entry point.
+ *
+ * Usage:
+ *   solo-cto-agent do "fix the login bug in tribo"
+ *   solo-cto-agent do "improve the hero section typography on the landing page"
+ *
+ * What it does:
+ *   1. Loads tracked repos from the saved wizard selection (bin/repo-discovery).
+ *   2. Asks Claude to translate the NL order into a structured issue spec.
+ *   3. Creates the issue on the target product repo with an `agent-{claude|codex}`
+ *      label so existing orchestrator workflows pick it up and run the real
+ *      implementation agent.
+ *
+ * Environment:
+ *   ANTHROPIC_API_KEY   required (for intent parsing)
+ *   GITHUB_TOKEN        required (to create the issue)
+ *
+ * We DO NOT write code here. The code is written by the implementing
+ * worker (claude-auto.yml / codex-auto.yml) once the labeled issue lands.
+ */
+
+"use strict";
+
+const { parseIntent, dispatchOrder } = require("./lib/nl-orchestrator");
+let repoDiscovery;
+try {
+  repoDiscovery = require("./repo-discovery");
+} catch (_) {
+  repoDiscovery = null;
+}
+
+function printHelp() {
+  console.log(`do — issue a natural-language work order
+
+Usage:
+  solo-cto-agent do "<natural language instruction>"
+
+Options:
+  --dry-run          Print the parsed intent without creating an issue
+  --repo owner/name  Override auto-selected target repo
+  --agent claude|codex  Force a specific implementer (default: LLM decides)
+  --help, -h         Show this
+
+Setup:
+  - Run \`solo-cto-agent init --wizard\` to discover and save tracked repos.
+  - Set ANTHROPIC_API_KEY (for intent parsing).
+  - Set GITHUB_TOKEN (for issue creation).
+
+Examples:
+  solo-cto-agent do "fix the staging deploy error I saw in tribo"
+  solo-cto-agent do "redesign the login hero on ohmywork — cleaner, less gradient" --agent claude
+  solo-cto-agent do "add unit tests for the ARPU calculator in tribo" --agent codex
+`);
+}
+
+function parseArgs(argv) {
+  const out = { text: null, dryRun: false, repo: null, agent: null, help: false };
+  const rest = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--help" || a === "-h") out.help = true;
+    else if (a === "--dry-run") out.dryRun = true;
+    else if (a === "--repo" && argv[i + 1]) {
+      out.repo = argv[++i];
+    } else if (a === "--agent" && argv[i + 1]) {
+      out.agent = argv[++i];
+    } else {
+      rest.push(a);
+    }
+  }
+  out.text = rest.join(" ").trim();
+  return out;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(3)); // slice 3: node, cli.js, "do"
+  if (args.help || !args.text) {
+    printHelp();
+    process.exit(args.help ? 0 : 1);
+  }
+
+  // 1. Tracked repos
+  if (!repoDiscovery) {
+    console.error("❌ repo-discovery module missing — reinstall solo-cto-agent.");
+    process.exit(1);
+  }
+  const saved = repoDiscovery.loadSelection();
+  if (!saved || !Array.isArray(saved.discovered) || saved.discovered.length === 0) {
+    console.error("❌ No tracked repos saved. Run `solo-cto-agent init --wizard` first.");
+    process.exit(1);
+  }
+  // If user selected a subset, only consider those; otherwise all discovered.
+  const selectedSet = new Set(saved.selected || []);
+  const trackedRepos = saved.discovered.filter((r) =>
+    selectedSet.size === 0 ? true : selectedSet.has(r.name)
+  );
+
+  if (args.repo) {
+    // --repo override: accept only if in the tracked list
+    const hit = trackedRepos.find((r) => (r.fullName || r.name) === args.repo);
+    if (!hit) {
+      console.error(`❌ --repo ${args.repo} is not in your tracked repo list.`);
+      console.error(`   Tracked: ${trackedRepos.map((r) => r.fullName || r.name).join(", ")}`);
+      process.exit(1);
+    }
+  }
+
+  // 2. Anthropic client — thin fetch shim so solo-cto-agent keeps zero
+  //    runtime deps. The orchestrator worker uses the real SDK (installed
+  //    by its workflow) but the CLI doesn't need it.
+  if (!process.env.ANTHROPIC_API_KEY) {
+    console.error("❌ ANTHROPIC_API_KEY not set. Needed to parse natural-language intent.");
+    process.exit(1);
+  }
+  const anthropicClient = buildAnthropicFetchClient(process.env.ANTHROPIC_API_KEY);
+
+  // 3. GitHub client (shell out to gh CLI to keep deps small). We wrap the
+  // ghApi shape the nl-orchestrator expects around gh.
+  const ghApi = buildGhApi(args.dryRun);
+
+  // 4. Run
+  try {
+    const intent = await parseIntent({ userText: args.text, trackedRepos, anthropicClient });
+    if (args.repo) intent.repo = args.repo;
+    if (args.agent) intent.agent = args.agent;
+
+    if (args.dryRun) {
+      console.log(JSON.stringify(intent, null, 2));
+      console.log("\n(dry-run — no issue created)");
+      return;
+    }
+
+    const result = await dispatchOrder({ intent, ghApi });
+    console.log(`✅ Issue created: ${result.issueUrl}`);
+    console.log(`   Repo:       ${result.repo}`);
+    console.log(`   Agent:      ${result.agent}`);
+    console.log(`   Scope:      ${result.scope}`);
+    console.log(`   Labels:     ${result.labels.join(", ")}`);
+    console.log(`\nThe '${result.agent}-auto' workflow will pick this up and open a PR.`);
+  } catch (err) {
+    console.error(`❌ ${err.message}`);
+    process.exit(1);
+  }
+}
+
+/**
+ * Thin Octokit-shaped client that only implements the methods nl-orchestrator
+ * actually calls. Uses `gh api` so we don't pull in @octokit/rest at runtime.
+ * Set dry=true to skip writes entirely (returns a stub).
+ */
+function buildGhApi(dry) {
+  const { execFileSync } = require("child_process");
+  return {
+    issues: {
+      create: async ({ owner, repo, title, body, labels }) => {
+        if (dry) {
+          return { data: { html_url: "(dry-run)", number: 0 } };
+        }
+        const payload = JSON.stringify({ title, body, labels });
+        const out = execFileSync("gh", ["api", "-X", "POST", `/repos/${owner}/${repo}/issues`, "--input", "-"], {
+          input: payload,
+          encoding: "utf8",
+          stdio: ["pipe", "pipe", "pipe"],
+        });
+        const data = JSON.parse(out);
+        return { data };
+      },
+    },
+  };
+}
+
+/**
+ * Anthropic client shim with just the `.messages.create` method the
+ * nl-orchestrator expects, calling the public REST endpoint directly.
+ * Keeps the CLI free of `@anthropic-ai/sdk` as a runtime dep.
+ */
+function buildAnthropicFetchClient(apiKey) {
+  return {
+    messages: {
+      create: async ({ model, max_tokens, temperature, system, messages }) => {
+        const res = await fetch("https://api.anthropic.com/v1/messages", {
+          method: "POST",
+          headers: {
+            "x-api-key": apiKey,
+            "anthropic-version": "2023-06-01",
+            "content-type": "application/json",
+          },
+          body: JSON.stringify({ model, max_tokens, temperature, system, messages }),
+        });
+        if (!res.ok) {
+          const body = await res.text();
+          throw new Error(`Anthropic ${res.status}: ${body.slice(0, 300)}`);
+        }
+        return res.json();
+      },
+    },
+  };
+}
+
+module.exports = { main };
+
+if (require.main === module) {
+  main().catch((e) => {
+    console.error(e.message);
+    process.exit(1);
+  });
+}