From fc9b22b4905171e4e6f4a28210db46cc99447686 Mon Sep 17 00:00:00 2001 From: web3dev1337 <160291380+web3dev1337@users.noreply.github.com> Date: Fri, 6 Mar 2026 09:02:51 +1100 Subject: [PATCH 1/3] review: anrokx open PR review (796, 791, 790, 788) Co-Authored-By: Claude Opus 4.6 --- REVIEWS/2026-03-06-anrokx-open-prs.md | 102 ++++++++++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 REVIEWS/2026-03-06-anrokx-open-prs.md diff --git a/REVIEWS/2026-03-06-anrokx-open-prs.md b/REVIEWS/2026-03-06-anrokx-open-prs.md new file mode 100644 index 00000000..28ad309d --- /dev/null +++ b/REVIEWS/2026-03-06-anrokx-open-prs.md @@ -0,0 +1,102 @@ +# AnrokX Open PR Review — 2026-03-06 + +## Open PRs + +| PR | Title | Size | Branch | +|----|-------|------|--------| +| **#796** | fix: clean windows onboarding changes against main | +6382/-2785, 12 files | `fix/windows-onboarding-clean-main` | +| **#791** | fix(windows): prevent updater plugin startup panic | +5/-0, 1 file | `fix/windows-updater-plugin-config-startup` | +| **#790** | test: fix windows CI recovery cleanup tests | +10/-10, 2 files | `fix/windows-build-verification` | +| **#788** | feat: add serverOnlyFileWatching user setting | +115/-1, 9 files | `feature/server-only-file-watching` | + +## Recently Merged (last 48hrs) + +| PR | Title | Merged | Size | +|----|-------|--------|------| +| #794 | feat: polish windows onboarding UX and setup detection | Mar 4 | +3245/-476, 9 files | +| #793 | feat(onboarding): guide dependency setup step-by-step | Mar 3 | +303/-62, 4 files | + +--- + +## PR #796 — Windows Onboarding Wizard (main review) + +Full first-run dependency wizard for Windows users. Checks for Git, Node, npm, GitHub CLI, Claude Code, and Codex CLI, then guides install via winget/PowerShell. + +### Medium Issues + +1. **Dead code: `guidance` variable** (client/app.js) — ~60 lines computing a variable that is never rendered in the template. Remove or wire it up. + +2. **Memory leak in `setupActionRuns`** (server/setupActionService.js) — `setupActionRuns` and `latestRunByActionId` Maps grow unboundedly with no cleanup/TTL. Add pruning. + +3. **Empty updater `pubkey`** (src-tauri/tauri.conf.json) — `pubkey: ""` prevents the startup panic but could silently accept unsigned updates. Set a real key or remove updater config entirely. + +4. **Duplicated Windows tool path logic** — Both `diagnosticsService.js` and `setupActionService.js` independently resolve Windows tool paths (~50 lines each). Extract a shared module to prevent divergence. + +5. **`autoCreate: true` behavioral change** (server/workspaceManager.js) — Changed from `false` to `true`. Existing users will see worktrees auto-created on new workspaces. Should be documented in PR description. + +6. **`stdout`/`stderr` nulled for ALL platforms** (src-tauri/src/main.rs) — Backend crash output is lost on all platforms, not just Windows. Consider routing to a log file. + +### Low Issues + +7. **Unescaped `statusText`/`runLabel`/`nextLabel`** in HTML template — Currently safe (hardcoded values) but violates defense-in-depth. Wrap in `escapeHtml()`. + +8. **`configureGitIdentity` platform-locked to win32** — `git config --global` works everywhere. The guard is unnecessary. + +9. **1,400-line method** (`setupDependencySetupWizard`) — Should be extracted to its own file (e.g. `client/dependency-wizard.js`). + +10. **Inline `require('child_process')`** inside route handler in server/index.js — Minor style inconsistency, already required elsewhere. + +### What's Good + +- Security is solid: URL validation on `open-url` endpoint, `escapeHtml()` used consistently, command injection surface is closed (hardcoded action IDs only) +- Workspace startup race condition fixed properly with `workspaceSystemReady` promise gate +- Toast notification system rewrite is a clean improvement over the old inline-style approach +- Scrollbar theming well-implemented with `@supports` fallback for `color-mix()` +- ARIA attributes on the onboarding modal +- CSS specificity fix in notifications.js scopes generic class names properly + +### Architecture Note + +`setupActionService.js` does NOT follow the singleton class pattern used by every other service (SessionManager, WorkspaceManager, etc.). Uses module-level Maps with plain exported functions. Works fine but breaks consistency. + +--- + +## PR #791 — Updater Plugin Fix + +**5 lines.** Adds `plugins.updater.pubkey: ""` to `tauri.conf.json` to prevent Tauri crash on Windows packaged builds. Correct fix for the immediate panic. Same empty pubkey concern as noted in #796 review. + +**Note:** This commit is cherry-picked into #796, so if #796 merges first, #791 can be closed as redundant. + +--- + +## PR #790 — Test Fixes + +**+10/-10, 2 files.** Updates stale test expectations: +- `clearAgent` → `markAgentInactive` (matching current behavior) +- Seeds in-memory state directly instead of mocking `loadWorkspaceState` + +Clean, correct, minimal. Should merge. + +--- + +## PR #788 — Server-Only File Watching + +**+115/-1, 9 files.** Adds `serverOnlyFileWatching` toggle so client-only file changes don't restart nodemon. + +- New `scripts/dev-server.js` launcher reads user-settings.json at startup +- Settings UI toggle under new "Developer" section +- Follows existing patterns well +- Includes `ai-memory/` files that should probably be excluded from the PR + +Should merge. + +--- + +## Merge Recommendations + +| Priority | PR | Action | +|----------|----|--------| +| 1 | **#790** | Merge as-is | +| 2 | **#788** | Merge (optionally remove ai-memory files first) | +| 3 | **#791** | Merge, file follow-up for real pubkey | +| 4 | **#796** | Address medium issues (dead code, memory leak, escape hardening), then merge | From 3ffd62d20bedcebfe31db8c3a829c511592c8854 Mon Sep 17 00:00:00 2001 From: web3dev1337 <160291380+web3dev1337@users.noreply.github.com> Date: Sun, 8 Mar 2026 22:21:41 +1100 Subject: [PATCH 2/3] docs: rewrite README to reflect actual repository state - Remove marketing fluff ("Revolutionary Feature") and personal project references - Add accurate prerequisites section for new users - Document the Tauri desktop app, diff viewer, commander, tabs, kanban board - Update architecture section to reflect actual scale (83 server modules, 24 client modules, 116 tests) - Add proper install instructions for both web and Windows desktop - Document cascaded config system, CI workflows, dual-instance setup - Replace stale internal PLANS/ references with user-facing content Co-Authored-By: Claude Opus 4.6 --- README.md | 385 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 203 insertions(+), 182 deletions(-) diff --git a/README.md b/README.md index 8d25bd68..7e75367e 100644 --- a/README.md +++ b/README.md @@ -1,212 +1,233 @@ -# Agent Orchestrator (repo: `claude-orchestrator`) - -A multi-workspace development environment for AI coding agent sessions (Claude Code, Codex) with dynamic repository management, mixed-repo workspaces, and one-click startup. - -> Note: the repository is still named `claude-orchestrator` for historical reasons. The UI/product name is **Agent Orchestrator**. - -## 🚀 Features - -### 🎯 **Multi-Workspace Management** -- **Unlimited Workspaces**: Switch between HyFire, Epic Survivors, websites, writing projects -- **Dashboard UI**: Visual workspace selection with activity indicators -- **Dynamic Configuration**: 1-16 terminal pairs per workspace -- **Project Type Awareness**: Auto-detects Hytopia, MonoGame, website, writing projects - -### 🧠 **Process Layer (Tiers + Queue + Risk + Prompts + Dependencies)** -- **Workflow Modes**: Focus (T1–T2) / Review (all; opens Queue) / Background (T3–T4) -- **Tier Tagging**: Per-agent tier selector (`None/T1–T4`) + tier filters -- **Review Inbox (“📥 Queue”)**: Unified PR/worktree/session list with Next/Prev navigation -- **Focus Helpers**: `T2 Auto/Always` + `Swap T2` auto-switch while Tier 1 is busy -- **Risk Metadata**: Base project risk + per-task change risk + `pFailFirstPass` + `verifyMinutes` -- **Prompt Artifacts**: Store massive prompts locally (private by default) with optional Trello embed -- **Dependencies**: - - Trello-backed: checklist convention named `Dependencies` - - Orchestrator-native: stored in local task records for non-Trello tasks -- **Review Automation (v1)**: - - Queue: “Auto Reviewer” for Tier 3 PRs + manual “Reviewer” and “Fixer” actions - - Dependency graph modal + “pick from queue” dependency linking - -### 🛠️ **Mixed-Repository Workspaces** -- **Revolutionary Feature**: Combine terminals from multiple repositories in one workspace -- **Example**: 2 HyFire + 4 Epic Survivors + 1 Website terminals together -- **Per-Terminal Buttons**: Each terminal shows repo-appropriate controls -- **Conflict Detection**: Smart indicators for worktree usage across workspaces - -### ⚡ **Dynamic Worktree Management** -- **Auto-Creation**: Creates git worktrees on-demand when switching workspaces -- **On-Demand Expansion**: Add more worktrees via "+ Add Worktree" button -- **Deep Repository Scanning**: Finds all projects (HyFire2, Epic Survivors, scripts, etc.) -- **Smart Conflict Detection**: Shows ⚠️ In use vs ✅ Available status - -### 🎨 **Advanced UI Components** -- **Workspace Creation Wizard**: 3-step guided setup with auto-type detection -- **Enhanced Sidebar**: Quick links, worktree management, global shortcuts -- **Cross-Workspace Notifications**: Background monitoring with muting controls -- **Launch Settings Templates**: Project-type specific configuration UIs - -### 🔧 **Zero-Friction Workflow** -- **One-Click Startup**: `orchestrator` command launches everything -- **Desktop Integration**: Click shortcut → auto-opens browser -- **Auto-Update**: Git pull on startup with dependency management -- **Smart Detection**: Opens browser if already running - -## 📊 Quick Start - -### Installation (WSL/Linux) -```bash -# Navigate to orchestrator directory -cd ~/GitHub/tools/automation/claude-orchestrator/claude-orchestrator-dev +# Agent Orchestrator + +A multi-workspace terminal orchestrator for AI coding agents (Claude Code, Codex CLI). Manages unlimited concurrent sessions across multiple repositories with browser-like tabs, dynamic git worktrees, and a native Windows desktop app. + +> The repository is named `claude-orchestrator` for historical reasons. The product name is **Agent Orchestrator**. + +## What It Does + +Agent Orchestrator gives you a single UI to run and monitor many AI coding sessions at once. Each workspace can hold 1-16 terminal pairs (agent + server), drawn from any combination of your git repositories. Workspaces live in browser-like tabs so you can switch between projects without losing terminal state. + +Key capabilities: + +- **Multi-workspace tabs** with full state isolation (terminals, sessions, scroll positions) +- **Mixed-repository workspaces** combining terminals from different repos in one view +- **Dynamic git worktree management** with auto-creation and conflict detection +- **Auto-discovery** of projects under `~/GitHub/` (configurable scan root) +- **Cascaded configuration** at 5 hierarchy levels (global, category, framework, project, worktree) +- **Process workflow layer** with tier tagging (T1-T4), review queue, risk metadata, and prompt artifacts +- **Commander panel** for a top-level AI that orchestrates other sessions +- **Projects kanban board** for tracking work across workspaces +- **Diff viewer** for AI-assisted code review (separate sub-app on its own port) +- **Native Windows app** via Tauri with bundled Node.js backend and auto-updater +- **First-run diagnostics** that check prerequisites and offer one-click repairs + +## Prerequisites + +| Requirement | Notes | +|-------------|-------| +| **Node.js** v18+ | Runtime for the backend server | +| **Git** | Required for worktree operations | +| **npm** | Comes with Node.js | + +Optional but recommended: -# Install deps -npm ci +| Tool | Purpose | +|------|---------| +| GitHub CLI (`gh`) | PR review/merge workflows, commander features | +| Claude Code CLI | AI agent sessions | +| Codex CLI | Alternative AI agent sessions | +| Rust + Cargo | Only if building the native desktop app | -# Run migration to set up workspace system -node scripts/migrate-to-workspaces.js +On first launch, the diagnostics panel shows what's installed and what's missing, with repair actions for common issues. -# (Optional) Install one-click startup shortcuts -bash scripts/install-startup.sh +## Quick Start + +### Web Mode (Linux / WSL / macOS) + +```bash +git clone https://github.com/web3dev1337/claude-orchestrator.git +cd claude-orchestrator + +# Create .env with your port preferences +cat > .env << 'EOF' +ORCHESTRATOR_PORT=3000 +CLIENT_PORT=2080 +DIFF_VIEWER_PORT=7655 +LOG_LEVEL=info +NODE_ENV=development +ENABLE_FILE_WATCHING=true +EOF + +npm install +cd diff-viewer && npm install && cd .. + +npm run dev +# Server starts on :3000, UI on :2080 ``` -### Installation (Windows native) -- Follow `WINDOWS_QUICK_START.md` (short) or `WINDOWS_BUILD_GUIDE.md` (full). -- Recommended “ready to sell” path is the Tauri build: `npm run tauri:build` (creates an installer). +Open `http://localhost:2080` in your browser. + +### Windows Desktop App (Tauri) + +If you have a pre-built installer (`.msi` or `.exe`), just run it. The app bundles Node.js and all dependencies — no dev tools needed. + +To build from source: -### Launch Orchestrator ```bash -# Command line (after install) -orchestrator +# Requires: Node.js, Rust, Visual Studio 2022 (C++ workload) +npm install +npm run tauri:build +# Produces installer in src-tauri/target/release/bundle/ +``` -# Or desktop shortcut -# Click "Claude Orchestrator" icon +The desktop app shows a bootstrap screen on launch, spawns the Node.js backend automatically, and opens the UI once the server is ready (~3-5 seconds). -# Or manual startup -npm run dev +### First Time Setup + +1. Launch the app (web or desktop) +2. The dashboard shows available workspaces (empty on first run) +3. Click **"Create New"** to open the workspace wizard +4. The wizard auto-scans `~/GitHub/` for git repositories, grouped by category +5. Pick a repository (or enter a custom path), set terminal count, and create +6. Your workspace is ready — terminals spawn automatically + +## Architecture + +``` +claude-orchestrator/ +├── server/ # Express.js backend (83 service modules, ~41k lines) +│ ├── index.js # Entry point, Express + Socket.IO setup +│ ├── sessionManager.js # Terminal session lifecycle +│ ├── workspaceManager.js # Workspace CRUD, mixed-repo orchestration +│ ├── worktreeHelper.js # Git worktree creation and conflict resolution +│ ├── statusDetector.js # Agent session state monitoring +│ ├── commanderService.js # Top-level AI orchestration +│ ├── projectBoardService.js # Kanban board backend +│ ├── configDiscoveryService.js # Cascaded config resolution +│ ├── diagnosticsService.js # First-run checks and repairs +│ └── ... # 74 more service modules +├── client/ # Vanilla JS frontend (24 modules) +│ ├── app.js # Main application, Socket.IO client +│ ├── terminal-manager.js # XTerm.js terminal grid +│ ├── workspace-tab-manager.js # Browser-like tab system +│ ├── dashboard.js # Workspace cards and navigation +│ ├── workspace-wizard.js # 3-step workspace creation +│ ├── commander-panel.js # Commander AI interface +│ ├── projects-board.js # Kanban drag-and-drop board +│ └── ... # 17 more client modules +├── src-tauri/ # Rust/Tauri native desktop app +│ ├── src/main.rs # Backend spawning, port management, auth +│ ├── src/terminal.rs # Native terminal module +│ ├── src/file_watcher.rs # File watching via notify-rs +│ └── tauri.conf.json # App metadata, bundling, updater config +├── diff-viewer/ # Standalone diff/review sub-app +├── templates/launch-settings/ # Per-project-type button/flag configs +├── scripts/ # Build, migration, release, and CI scripts +├── tests/ +│ ├── unit/ # 81 unit tests (Jest) +│ └── e2e/ # 35 end-to-end tests (Playwright) +├── .github/workflows/ # CI: tests, gitleaks, Windows Tauri build +├── config/ # Shared configuration files +├── plugins/ # Plugin system (extensible) +└── docs/ # Additional documentation ``` -### Process docs (resume-safe) -- `PLANS/2026-01-25/WORKFLOW_TIER_RISK_PROMPTS.md` (what’s shipped vs missing) -- `PLANS/2026-01-25/BRAIN_DUMP_IMPLEMENTATION_PLAN.md` (brain dump → PR-sized plan) -- `PLANS/2026-01-25/DATA_MODEL.md` (where the data lives) - -### Tier persistence (refresh-safe) -Tier tagging (T1–T4) persists across page refreshes and server restarts because it is stored in task records: -- `~/.orchestrator/task-records.json` (`session:`, `pr:owner/repo#123`, `worktree:/path`) - -### Create Your First Custom Workspace -1. **Access Dashboard**: http://localhost:2080 -2. **Click "Create New"** → Opens workspace wizard -3. **Select Repository**: Choose from categorized list (Hytopia Games, MonoGame Games, Writing, etc.) -4. **Configure**: Set name, terminal count, access level -5. **Review & Create**: Workspace ready immediately - -### Add Mixed-Repo Terminals -1. **In any workspace** → Click **"+ Add Worktree"** in sidebar -2. **Browse Categories**: Hytopia Games, MonoGame Games, Writing, Tools -3. **Select Worktree**: See ⚠️ In use vs ✅ Available status for each work1-8 -4. **Add to Workspace**: Creates mixed-repo workspace automatically - -## 🏗️ Architecture - -### Backend Services -- **WorkspaceManager**: Core workspace CRUD with JSON config persistence -- **SessionManager**: Dynamic session management for single/mixed-repo workspaces -- **WorktreeHelper**: Automated git worktree creation with conflict resolution -- **Deep Scanner**: Recursive project discovery with path-based type detection - -### Frontend Components -- **Dashboard**: Visual workspace cards with activity and stats -- **WorkspaceSwitcher**: Header dropdown for instant workspace switching -- **WorkspaceWizard**: Guided workspace creation with repository categorization -- **Advanced Add Worktree**: Multi-repo selection with conflict detection - -### Configuration +### Runtime Data + ``` ~/.orchestrator/ -├── config.json # Master configuration -├── workspaces/ # Workspace definitions -│ ├── hyfire2.json # Single-repo workspace -│ ├── epic-survivors.json # Single-repo workspace -│ └── custom-dev.json # Mixed-repo workspace -├── templates/ # Project type templates -└── session-states/ # Persistent session states +├── config.json # Global settings +├── workspaces/ # Workspace definitions (JSON per workspace) +├── task-records.json # Tier tags, ticket links, risk metadata +└── session-states/ # Persisted terminal states ``` -## 🎯 Workspace Types - -### Single-Repository Workspaces -Traditional approach where all terminals come from one repository: -- **HyFire 2**: 8 terminal pairs from HyFire repository -- **Epic Survivors**: 1-8 terminal pairs from Epic Survivors repository -- **Website**: 1-4 terminal pairs from website repository +### Key Patterns -### Mixed-Repository Workspaces -Revolutionary approach combining terminals from multiple repositories: -- **Custom Dev**: 2 HyFire + 4 Epic Survivors + 1 Website terminals -- **Game Focus**: 4 HyFire + 2 MonoGame + 2 Tools terminals -- **Any Combination**: Complete flexibility in terminal composition +- **Service-based architecture**: Each `server/*.js` file is a focused service module +- **Singleton managers**: `SessionManager.getInstance()`, `WorkspaceManager.getInstance()` +- **Real-time communication**: Socket.IO events between server and all clients +- **Cascaded configuration**: 5-level merge (global → category → framework → project → worktree) +- **Event-driven**: Terminal output, session state changes, and workspace switches all via events -## 🔧 Development +## Available Scripts -### Project Structure +```bash +# Development +npm run dev # Backend + UI (web mode) +npm run dev:full # Backend + UI + Tauri native app +npm run dev:server # Backend only +npm run dev:client # UI dev server only +npm run tauri:dev # Tauri app with hot reload + +# Testing +npm run test # All tests (unit + e2e) +npm run test:unit # Jest unit tests +npm run test:e2e:safe # Playwright e2e (auto-picks safe port) + +# Building +npm run tauri:build # Build native Windows/Linux app + +# Release prep +npm run audit:public-release # Scan for secrets/credentials +npm run report:release-readiness # Generate readiness report +npm run check:command-surface # Check for API surface drift ``` -claude-orchestrator-dev/ -├── server/ # Backend services -│ ├── workspaceManager.js # Core workspace management -│ ├── sessionManager.js # Session lifecycle with mixed-repo support -│ ├── worktreeHelper.js # Dynamic worktree creation -│ └── workspaceSchemas.js # Single/mixed workspace schemas -├── client/ # Frontend components -│ ├── dashboard.js # Workspace dashboard UI -│ ├── workspace-switcher.js # Header dropdown switcher -│ ├── workspace-wizard.js # Workspace creation wizard -│ └── app.js # Main orchestrator application -├── templates/ # Project type templates -│ └── launch-settings/ # Launch configuration templates -├── scripts/ # Automation scripts -│ ├── migrate-to-workspaces.js # Migration from old config -│ ├── orchestrator-startup.sh # One-click startup -│ └── install-startup.sh # Desktop shortcut installer -└── ~/.orchestrator/ # User configuration directory + +## Configuration + +### Environment Variables (`.env`) + +```env +ORCHESTRATOR_PORT=3000 # Backend API port +CLIENT_PORT=2080 # UI dev server port +DIFF_VIEWER_PORT=7655 # Diff viewer port +LOG_LEVEL=info # Winston log level +NODE_ENV=development +ENABLE_FILE_WATCHING=true # Watch for file changes in worktrees ``` -### Available Scripts -```bash -npm run dev # Start backend + UI dev server -npm run dev:server # Start backend only (port 3000) -npm run dev:client # Start UI dev server only (port 2080) -npm run dev:full # Start backend + UI + tauri dev -npm run tauri:build # Build native app for distribution (Windows installer) -npm run tauri:dev # Native app development +### Cascaded Project Configs + +Place `.orchestrator-config.json` files at any level of your project hierarchy to define custom terminal buttons, game modes, and flags. Configs merge from global down to worktree level. + +```json +{ + "buttons": { + "claude": { "review": { "label": "Review", "command": "gh pr view --web" } }, + "server": { "play": { "label": "Play", "command": "npm run dev" } } + } +} ``` -## 📈 Capabilities +## Running Two Instances (Dev + Production) + +For developing the orchestrator itself while using it for daily work: + +| Instance | Directory | Ports | Purpose | +|----------|-----------|-------|---------| +| Production | `claude-orchestrator/master` | 3000 / 2080 / 7655 | Daily AI agent work | +| Development | `claude-orchestrator/claude-orchestrator-dev` | 4000 / 2081 / 7656 | Modifying the orchestrator | + +Each instance gets its own `.env` with different port numbers. Both can run simultaneously. + +## CI / CD + +Three GitHub Actions workflows: -### Repository Discovery -- **Deep Scanning**: Finds individual projects in nested folder structures -- **Auto-Type Detection**: Determines project type from folder path -- **Categories**: Hytopia Games, MonoGame Games, Websites, Writing, Tools -- **Project Examples**: HyFire2, Epic Survivors, cb-fry-scripts, 2d-test, etc. +- **`tests.yml`** — Unit tests on every push +- **`gitleaks.yml`** — Secret scanning on every push +- **`windows.yml`** — Windows unit tests + Tauri installer build (on tags or manual dispatch) -### Workspace Management -- **Unlimited Workspaces**: Create as many as needed -- **Dynamic Terminal Counts**: 1-16 pairs per workspace -- **Clean Isolation**: Perfect separation between workspace sessions -- **Instant Switching**: < 5 second workspace transitions +## Contributing -### Advanced Features -- **Worktree Conflict Detection**: Visual status indicators (⚠️ In use / ✅ Available) -- **Mixed-Repo Composition**: Any combination of repositories in one workspace -- **3-Layer Button System**: Game → Framework → Project specific controls -- **Background Monitoring**: Cross-workspace notifications with muting +See [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow. -## 🚀 Getting Started +## Security -1. **Installation**: WSL/Linux: `bash scripts/install-startup.sh` (optional) • Windows: `WINDOWS_QUICK_START.md` -2. **Launch**: `npm run dev` (or `orchestrator` if installed) -3. **Create Workspace**: Dashboard → Create New → Select repository -4. **Add Mixed Terminals**: "+ Add Worktree" → Browse repositories -5. **Enjoy**: Complete development environment ready! +See [SECURITY.md](SECURITY.md) for reporting vulnerabilities. ---- +## License -**Transforms Claude Orchestrator from single-project tool to unlimited multi-workspace development environment with mixed-repository support and zero-friction workflows.** +[MIT](LICENSE) From 95a06849e64336bb439fbf83a74f74a452f66dad Mon Sep 17 00:00:00 2001 From: web3dev1337 <160291380+web3dev1337@users.noreply.github.com> Date: Sun, 8 Mar 2026 22:28:17 +1100 Subject: [PATCH 3/3] chore: organize root markdown files into docs/ structure MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Move 31 .md files out of root into organized docs/ subdirectories: - docs/historical/ — 25 archived plans, implementation notes, old audits - docs/windows/ — Windows install and build guides - docs/diff-viewer/ — Diff viewer setup and features - docs/ — Commander API ref, latest security audit Root now has only 5 essential files: README.md, CLAUDE.md, CODEBASE_DOCUMENTATION.md, CONTRIBUTING.md, SECURITY.md Update references in CLAUDE.md and scripts/public-release-audit.js to point to new file locations. Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 5 ++--- README.md | 3 +++ COMMANDER_CLAUDE.md => docs/COMMANDER_CLAUDE.md | 0 .../PUBLIC_RELEASE_AUDIT_2026-02-06.md | 0 .../diff-viewer/DIFF_VIEWER_FEATURES.md | 0 .../diff-viewer/INSTALL_DIFF_VIEWER.md | 0 .../historical/ADVANCED_DIFF_VIEWER_PLAN.md | 0 .../historical/COMPLETE_IMPLEMENTATION.md | 0 COWORKER_SETUP.md => docs/historical/COWORKER_SETUP.md | 0 .../historical/COWORKER_SETUP_GUIDE.md | 0 DOCUMENTATION.md => docs/historical/DOCUMENTATION.md | 0 FINAL_PLAN.md => docs/historical/FINAL_PLAN.md | 0 .../historical/GAP_ANALYSIS_2026-01-17.md | 0 .../historical/GIT_STATUS_COMPARISON.md | 0 .../historical/IMPLEMENTATION_NOTES.md | 0 .../historical/IMPLEMENTATION_PLAN.md | 0 .../historical/IMPLEMENTATION_STATUS.md | 0 .../historical/IMPROVEMENT_ROADMAP.md | 0 .../historical/PHASE2_IMPLEMENTATION_PLAN.md | 0 .../historical/PROJECT_CREATION_PLAN.md | 0 PR_CLEANUP_PLAN.md => docs/historical/PR_CLEANUP_PLAN.md | 0 PR_SUMMARY.md => docs/historical/PR_SUMMARY.md | 0 .../historical/PUBLIC_RELEASE_AUDIT_2026-02-04.md | 0 .../historical/PUBLIC_RELEASE_AUDIT_2026-02-05.md | 0 QUICK_START.md => docs/historical/QUICK_START.md | 0 .../historical/QUICK_START_SUMMARY.md | 0 .../historical/REVISED_WORKSPACE_PLAN.md | 0 .../historical/SETUP_INSTRUCTIONS.md | 0 .../historical/SYSTEM_OVERVIEW_PRESENTATION.md | 0 .../historical/USAGE_CLARIFICATION.md | 0 .../historical/WORKSPACE_ANALYSIS.md | 0 .../windows/WINDOWS_BUILD_GUIDE.md | 0 .../windows/WINDOWS_QUICK_START.md | 0 scripts/public-release-audit.js | 2 +- 34 files changed, 6 insertions(+), 4 deletions(-) rename COMMANDER_CLAUDE.md => docs/COMMANDER_CLAUDE.md (100%) rename PUBLIC_RELEASE_AUDIT_2026-02-06.md => docs/PUBLIC_RELEASE_AUDIT_2026-02-06.md (100%) rename DIFF_VIEWER_FEATURES.md => docs/diff-viewer/DIFF_VIEWER_FEATURES.md (100%) rename INSTALL_DIFF_VIEWER.md => docs/diff-viewer/INSTALL_DIFF_VIEWER.md (100%) rename ADVANCED_DIFF_VIEWER_PLAN.md => docs/historical/ADVANCED_DIFF_VIEWER_PLAN.md (100%) rename COMPLETE_IMPLEMENTATION.md => docs/historical/COMPLETE_IMPLEMENTATION.md (100%) rename COWORKER_SETUP.md => docs/historical/COWORKER_SETUP.md (100%) rename COWORKER_SETUP_GUIDE.md => docs/historical/COWORKER_SETUP_GUIDE.md (100%) rename DOCUMENTATION.md => docs/historical/DOCUMENTATION.md (100%) rename FINAL_PLAN.md => docs/historical/FINAL_PLAN.md (100%) rename GAP_ANALYSIS_2026-01-17.md => docs/historical/GAP_ANALYSIS_2026-01-17.md (100%) rename GIT_STATUS_COMPARISON.md => docs/historical/GIT_STATUS_COMPARISON.md (100%) rename IMPLEMENTATION_NOTES.md => docs/historical/IMPLEMENTATION_NOTES.md (100%) rename IMPLEMENTATION_PLAN.md => docs/historical/IMPLEMENTATION_PLAN.md (100%) rename IMPLEMENTATION_STATUS.md => docs/historical/IMPLEMENTATION_STATUS.md (100%) rename IMPROVEMENT_ROADMAP.md => docs/historical/IMPROVEMENT_ROADMAP.md (100%) rename PHASE2_IMPLEMENTATION_PLAN.md => docs/historical/PHASE2_IMPLEMENTATION_PLAN.md (100%) rename PROJECT_CREATION_PLAN.md => docs/historical/PROJECT_CREATION_PLAN.md (100%) rename PR_CLEANUP_PLAN.md => docs/historical/PR_CLEANUP_PLAN.md (100%) rename PR_SUMMARY.md => docs/historical/PR_SUMMARY.md (100%) rename PUBLIC_RELEASE_AUDIT_2026-02-04.md => docs/historical/PUBLIC_RELEASE_AUDIT_2026-02-04.md (100%) rename PUBLIC_RELEASE_AUDIT_2026-02-05.md => docs/historical/PUBLIC_RELEASE_AUDIT_2026-02-05.md (100%) rename QUICK_START.md => docs/historical/QUICK_START.md (100%) rename QUICK_START_SUMMARY.md => docs/historical/QUICK_START_SUMMARY.md (100%) rename REVISED_WORKSPACE_PLAN.md => docs/historical/REVISED_WORKSPACE_PLAN.md (100%) rename SETUP_INSTRUCTIONS.md => docs/historical/SETUP_INSTRUCTIONS.md (100%) rename SYSTEM_OVERVIEW_PRESENTATION.md => docs/historical/SYSTEM_OVERVIEW_PRESENTATION.md (100%) rename USAGE_CLARIFICATION.md => docs/historical/USAGE_CLARIFICATION.md (100%) rename WORKSPACE_ANALYSIS.md => docs/historical/WORKSPACE_ANALYSIS.md (100%) rename WINDOWS_BUILD_GUIDE.md => docs/windows/WINDOWS_BUILD_GUIDE.md (100%) rename WINDOWS_QUICK_START.md => docs/windows/WINDOWS_QUICK_START.md (100%) diff --git a/CLAUDE.md b/CLAUDE.md index 434f1970..38860e10 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -226,8 +226,6 @@ Because `main` is usually checked out in the `master/` worktree, **do not try to ## 🚨 CRITICAL: READ THESE FILES 🚨 **2. Read `CODEBASE_DOCUMENTATION.md`** - Contains system docs and file locations (READ THE ENTIRE FILE) -**3. Read `COMPLETE_IMPLEMENTATION.md`** - Multi-workspace system overview (ESSENTIAL) -**4. Read `PR_SUMMARY.md`** - Technical implementation details (FOR CHANGES) ## 🚨 CRITICAL: ALWAYS CREATE A PR WHEN DONE 🚨 **When you complete ANY feature or fix, you MUST create a pull request using `gh pr create`. This is mandatory. Add "Create PR" as your final checklist item to ensure you never forget.** @@ -287,7 +285,7 @@ Commander Claude is a special Claude Code instance that runs from the orchestrat **Read the full Commander instructions:** ```bash -cat ~/GitHub/tools/automation/claude-orchestrator/master/COMMANDER_CLAUDE.md +cat ~/GitHub/tools/automation/claude-orchestrator/master/docs/COMMANDER_CLAUDE.md ``` ### Port Detection (MANDATORY — do this first) @@ -413,6 +411,7 @@ Workspaces are stored in `~/.orchestrator/workspaces/`. Each workspace has: ### Important Files to Read First - `CODEBASE_DOCUMENTATION.md`: Comprehensive system overview +- `docs/COMMANDER_CLAUDE.md`: Commander AI API reference - `server/index.js`: Main backend entry point - `package.json`: Dependencies and scripts - `src-tauri/src/main.rs`: Tauri app entry point diff --git a/README.md b/README.md index 7e75367e..75d6df38 100644 --- a/README.md +++ b/README.md @@ -131,6 +131,9 @@ claude-orchestrator/ ├── config/ # Shared configuration files ├── plugins/ # Plugin system (extensible) └── docs/ # Additional documentation + ├── windows/ # Windows install and build guides + ├── diff-viewer/ # Diff viewer setup and features + └── historical/ # Archived plans and implementation notes ``` ### Runtime Data diff --git a/COMMANDER_CLAUDE.md b/docs/COMMANDER_CLAUDE.md similarity index 100% rename from COMMANDER_CLAUDE.md rename to docs/COMMANDER_CLAUDE.md diff --git a/PUBLIC_RELEASE_AUDIT_2026-02-06.md b/docs/PUBLIC_RELEASE_AUDIT_2026-02-06.md similarity index 100% rename from PUBLIC_RELEASE_AUDIT_2026-02-06.md rename to docs/PUBLIC_RELEASE_AUDIT_2026-02-06.md diff --git a/DIFF_VIEWER_FEATURES.md b/docs/diff-viewer/DIFF_VIEWER_FEATURES.md similarity index 100% rename from DIFF_VIEWER_FEATURES.md rename to docs/diff-viewer/DIFF_VIEWER_FEATURES.md diff --git a/INSTALL_DIFF_VIEWER.md b/docs/diff-viewer/INSTALL_DIFF_VIEWER.md similarity index 100% rename from INSTALL_DIFF_VIEWER.md rename to docs/diff-viewer/INSTALL_DIFF_VIEWER.md diff --git a/ADVANCED_DIFF_VIEWER_PLAN.md b/docs/historical/ADVANCED_DIFF_VIEWER_PLAN.md similarity index 100% rename from ADVANCED_DIFF_VIEWER_PLAN.md rename to docs/historical/ADVANCED_DIFF_VIEWER_PLAN.md diff --git a/COMPLETE_IMPLEMENTATION.md b/docs/historical/COMPLETE_IMPLEMENTATION.md similarity index 100% rename from COMPLETE_IMPLEMENTATION.md rename to docs/historical/COMPLETE_IMPLEMENTATION.md diff --git a/COWORKER_SETUP.md b/docs/historical/COWORKER_SETUP.md similarity index 100% rename from COWORKER_SETUP.md rename to docs/historical/COWORKER_SETUP.md diff --git a/COWORKER_SETUP_GUIDE.md b/docs/historical/COWORKER_SETUP_GUIDE.md similarity index 100% rename from COWORKER_SETUP_GUIDE.md rename to docs/historical/COWORKER_SETUP_GUIDE.md diff --git a/DOCUMENTATION.md b/docs/historical/DOCUMENTATION.md similarity index 100% rename from DOCUMENTATION.md rename to docs/historical/DOCUMENTATION.md diff --git a/FINAL_PLAN.md b/docs/historical/FINAL_PLAN.md similarity index 100% rename from FINAL_PLAN.md rename to docs/historical/FINAL_PLAN.md diff --git a/GAP_ANALYSIS_2026-01-17.md b/docs/historical/GAP_ANALYSIS_2026-01-17.md similarity index 100% rename from GAP_ANALYSIS_2026-01-17.md rename to docs/historical/GAP_ANALYSIS_2026-01-17.md diff --git a/GIT_STATUS_COMPARISON.md b/docs/historical/GIT_STATUS_COMPARISON.md similarity index 100% rename from GIT_STATUS_COMPARISON.md rename to docs/historical/GIT_STATUS_COMPARISON.md diff --git a/IMPLEMENTATION_NOTES.md b/docs/historical/IMPLEMENTATION_NOTES.md similarity index 100% rename from IMPLEMENTATION_NOTES.md rename to docs/historical/IMPLEMENTATION_NOTES.md diff --git a/IMPLEMENTATION_PLAN.md b/docs/historical/IMPLEMENTATION_PLAN.md similarity index 100% rename from IMPLEMENTATION_PLAN.md rename to docs/historical/IMPLEMENTATION_PLAN.md diff --git a/IMPLEMENTATION_STATUS.md b/docs/historical/IMPLEMENTATION_STATUS.md similarity index 100% rename from IMPLEMENTATION_STATUS.md rename to docs/historical/IMPLEMENTATION_STATUS.md diff --git a/IMPROVEMENT_ROADMAP.md b/docs/historical/IMPROVEMENT_ROADMAP.md similarity index 100% rename from IMPROVEMENT_ROADMAP.md rename to docs/historical/IMPROVEMENT_ROADMAP.md diff --git a/PHASE2_IMPLEMENTATION_PLAN.md b/docs/historical/PHASE2_IMPLEMENTATION_PLAN.md similarity index 100% rename from PHASE2_IMPLEMENTATION_PLAN.md rename to docs/historical/PHASE2_IMPLEMENTATION_PLAN.md diff --git a/PROJECT_CREATION_PLAN.md b/docs/historical/PROJECT_CREATION_PLAN.md similarity index 100% rename from PROJECT_CREATION_PLAN.md rename to docs/historical/PROJECT_CREATION_PLAN.md diff --git a/PR_CLEANUP_PLAN.md b/docs/historical/PR_CLEANUP_PLAN.md similarity index 100% rename from PR_CLEANUP_PLAN.md rename to docs/historical/PR_CLEANUP_PLAN.md diff --git a/PR_SUMMARY.md b/docs/historical/PR_SUMMARY.md similarity index 100% rename from PR_SUMMARY.md rename to docs/historical/PR_SUMMARY.md diff --git a/PUBLIC_RELEASE_AUDIT_2026-02-04.md b/docs/historical/PUBLIC_RELEASE_AUDIT_2026-02-04.md similarity index 100% rename from PUBLIC_RELEASE_AUDIT_2026-02-04.md rename to docs/historical/PUBLIC_RELEASE_AUDIT_2026-02-04.md diff --git a/PUBLIC_RELEASE_AUDIT_2026-02-05.md b/docs/historical/PUBLIC_RELEASE_AUDIT_2026-02-05.md similarity index 100% rename from PUBLIC_RELEASE_AUDIT_2026-02-05.md rename to docs/historical/PUBLIC_RELEASE_AUDIT_2026-02-05.md diff --git a/QUICK_START.md b/docs/historical/QUICK_START.md similarity index 100% rename from QUICK_START.md rename to docs/historical/QUICK_START.md diff --git a/QUICK_START_SUMMARY.md b/docs/historical/QUICK_START_SUMMARY.md similarity index 100% rename from QUICK_START_SUMMARY.md rename to docs/historical/QUICK_START_SUMMARY.md diff --git a/REVISED_WORKSPACE_PLAN.md b/docs/historical/REVISED_WORKSPACE_PLAN.md similarity index 100% rename from REVISED_WORKSPACE_PLAN.md rename to docs/historical/REVISED_WORKSPACE_PLAN.md diff --git a/SETUP_INSTRUCTIONS.md b/docs/historical/SETUP_INSTRUCTIONS.md similarity index 100% rename from SETUP_INSTRUCTIONS.md rename to docs/historical/SETUP_INSTRUCTIONS.md diff --git a/SYSTEM_OVERVIEW_PRESENTATION.md b/docs/historical/SYSTEM_OVERVIEW_PRESENTATION.md similarity index 100% rename from SYSTEM_OVERVIEW_PRESENTATION.md rename to docs/historical/SYSTEM_OVERVIEW_PRESENTATION.md diff --git a/USAGE_CLARIFICATION.md b/docs/historical/USAGE_CLARIFICATION.md similarity index 100% rename from USAGE_CLARIFICATION.md rename to docs/historical/USAGE_CLARIFICATION.md diff --git a/WORKSPACE_ANALYSIS.md b/docs/historical/WORKSPACE_ANALYSIS.md similarity index 100% rename from WORKSPACE_ANALYSIS.md rename to docs/historical/WORKSPACE_ANALYSIS.md diff --git a/WINDOWS_BUILD_GUIDE.md b/docs/windows/WINDOWS_BUILD_GUIDE.md similarity index 100% rename from WINDOWS_BUILD_GUIDE.md rename to docs/windows/WINDOWS_BUILD_GUIDE.md diff --git a/WINDOWS_QUICK_START.md b/docs/windows/WINDOWS_QUICK_START.md similarity index 100% rename from WINDOWS_QUICK_START.md rename to docs/windows/WINDOWS_QUICK_START.md diff --git a/scripts/public-release-audit.js b/scripts/public-release-audit.js index fe7a9e50..0172701e 100755 --- a/scripts/public-release-audit.js +++ b/scripts/public-release-audit.js @@ -12,7 +12,7 @@ const publicDocs = [ 'README.md', 'SECURITY.md', 'CONTRIBUTING.md', - 'WINDOWS_QUICK_START.md', + 'docs/windows/WINDOWS_QUICK_START.md', 'PLANS/2026-02-06/SELLABLE_WINDOWS_RELEASE_PLAYBOOK.md', 'scripts/windows-launchers/README.md' ];