From c8ff48e4f753cc85f35ba58ad4f4483145bf8676 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tuncay=20=C3=96lmez?= Date: Thu, 28 May 2026 21:55:06 +0300 Subject: [PATCH 1/3] docs: add coordinator mode roadmap --- docs/coordinator-mode-roadmap.md | 565 +++++++++++++++++++++++++++++++ 1 file changed, 565 insertions(+) create mode 100644 docs/coordinator-mode-roadmap.md diff --git a/docs/coordinator-mode-roadmap.md b/docs/coordinator-mode-roadmap.md new file mode 100644 index 0000000..4ff6745 --- /dev/null +++ b/docs/coordinator-mode-roadmap.md @@ -0,0 +1,565 @@ +# Next Codex Chat Brief + +Project name: Codex Engineering Workflow Pack, abbreviated as CEWP. + +Repo purpose: CEWP is an unofficial local-first skill pack for structured engineering workflows in Codex. It gives Codex reusable workflow skills for setup, diagnosis, TDD, PRD writing, issue slicing, handoff, prototyping, and architecture analysis. + +Current public state: the repo is public-facing as a small npm-distributed skill pack. The public surface is intentionally narrow: `.agents/skills/`, `README.md`, `docs/install.md`, `bin/cewp.js`, fallback installers, package metadata, and license. Internal planning, pilot notes, local cache, and old private docs are not part of the public surface. + +Current npm package name: `@setrathex/codex-engineering-workflow-pack`. + +Current CLI name: `cewp`. + +Current 10 skills: + +1. `setup-codex-engineering-workflow` +2. `diagnose` +3. `tdd` +4. `grill-with-docs` +5. `to-prd` +6. `to-issues` +7. `handoff` +8. `zoom-out` +9. `prototype` +10. `improve-codebase-architecture` + +Current CLI commands: + +```bash +cewp init +cewp init --mode repo +cewp init --mode repo --target "" +cewp init --mode repo --target "" --force +cewp init --mode global +cewp init --mode global --force +cewp doctor +cewp list +cewp --help +``` + +Recent important improvements: + +- npm CLI installer added for repo/global skill installation. +- `cewp doctor` added to validate installed skill folders. +- `cewp list` added to show installed/missing skills. +- CLI binary mapping fixed for `npx` usage. +- `--target` validation fixed so missing target values fail clearly. +- README polished with workflow recipes, install commands, and `rg`/ripgrep fallback notes. +- Package metadata polished with GitHub repository, homepage, bugs, license, keywords, and minimal `files`. + +Coordinator Mode idea: turn CEWP from a single-Codex workflow discipline pack into a local-first coordination layer for multiple Codex CLI sessions. The first version should coordinate 3-5 Codex sessions through local task board files, role prompts, report files, and a reviewer gate. It should work well in Warp or similar multi-pane terminal environments. + +Work to start on a new branch: design and then implement CEWP Coordinator Mode v0.2 as a new CLI/documentation layer without touching existing skill contents. + +First goal for the next chat: read this roadmap, tighten the v0.2 design, produce an implementation plan, and only then proceed to the MVP CLI skeleton after approval. Do not publish npm and do not edit existing skills. + +## 1. Current Product State + +CEWP currently ships as a local-first Codex skill pack. + +The main product is the 10-skill workflow set under: + +```txt +.agents/skills/ +``` + +The pack is installed through an npm CLI and fallback shell scripts. The installer copies only the approved skill folders and does not read secrets or project config. + +Install modes: + +- Repo install: copies skills into `/.agents/skills/`. +- Global install: copies skills into `$HOME/.agents/skills/`. +- Manual install: copy the 10 skill folders directly. + +The CLI supports: + +- `cewp init` for repo/global install. +- `cewp doctor` for install validation. +- `cewp list` for installed/missing skill inventory. + +The product approach is local-first: + +- Local markdown PRDs/issues/handoffs are preferred. +- GitHub publishing is optional and requires an explicit user request. +- Repo-scoped skills may be committed when the team wants shared workflow behavior. +- Local-only installs should use `.git/info/exclude` instead of project `.gitignore`. + +Public repo surface: + +- `.agents/skills/` +- `README.md` +- `docs/install.md` +- `bin/cewp.js` +- `install.ps1` +- `install.sh` +- `package.json` +- `.gitignore` +- `LICENSE` + +Package state visible from local files: + +- `package.json` name: `@setrathex/codex-engineering-workflow-pack` +- `package.json` version: `0.1.0-beta.5` +- CLI binary: `cewp` +- Secondary binary alias: `codex-engineering-workflow-pack` +- npm package files are limited to public product files. + +Publish status note: local files show `0.1.0-beta.5`, but npm dist-tags and GitHub release alignment should be verified before any future publish or release work. + +## 2. Coordinator Mode Vision + +CEWP Coordinator Mode will provide a local-first coordination layer for running multiple Codex CLI sessions against the same project. + +The target user flow is a Warp or similar terminal layout with 3-5 panes: + +- one Manager Codex session, +- one or more Worker Codex sessions, +- one Reviewer/Debugger Codex session. + +These sessions should not directly control each other. They coordinate through local files: + +- task board, +- task JSON files, +- role prompts, +- per-agent event logs, +- worker reports, +- reviewer reports, +- handoff notes. + +The first version must not be full automation. It should produce structure, prompts, and status visibility so the user can manually run each Codex pane with clear boundaries. + +## 3. Why This Belongs Inside CEWP + +Coordinator Mode belongs inside CEWP because it extends the existing product naturally. + +CEWP already provides single-agent engineering discipline: + +- `to-prd` turns ideas into durable product requirements. +- `to-issues` breaks work into vertical slices. +- `tdd` guides implementation through red-green-refactor. +- `diagnose` provides a systematic debugging loop. +- `zoom-out` maps unknown code areas. +- `improve-codebase-architecture` audits architecture friction. +- `handoff` preserves continuation context. + +Coordinator Mode adds a multi-agent coordination layer on top of those workflows. It does not replace the skills. It makes them easier to use when several Codex sessions are working in parallel. + +This should be a CEWP v0.2 module, not a separate product, because the value is the combination of workflow skills plus local orchestration discipline. + +## 4. Non-Goals For v0.2 + +v0.2 must stay small and safe. + +Non-goals: + +- No Codex process spawning. +- No terminal input automation. +- No auto merge. +- No auto push. +- No parallel edits in the same working tree. +- No remote service. +- No production code editing by the Manager role. +- No workers writing shared `board.json`. +- No `AGENTS.md` or `CLAUDE.md` assumption. +- No full autonomous endless loop. +- No npm publish until the feature is tested. +- No existing skill content changes. + +## 5. Core Architecture + +Runtime state lives under: + +```txt +.cewp/runs// +``` + +Recommended structure: + +```txt +.cewp/ + runs/ + / + run.json + board.json + plan.md + events/ + manager.jsonl + worker-a.jsonl + worker-b.jsonl + reviewer.jsonl + agents/ + manager.md + worker-a.md + worker-b.md + reviewer.md + tasks/ + task-001.json + task-002.json + prompts/ + manager-prompt.md + worker-a-prompt.md + worker-b-prompt.md + reviewer-prompt.md + reports/ + worker-a-report.md + worker-b-report.md + reviews/ + reviewer-report.md + handoff/ + run-handoff.md +``` + +Important architecture rules: + +- `board.json` is not multi-writer. +- Manager/CLI writes `board.json`. +- Workers read `board.json` and `tasks/*.json`. +- Each worker writes only its own report file and event file. +- Reviewer reads board, tasks, reports, diffs, and test output. +- Reviewer writes only review files and its own event file. +- CLI status reads board + reports + reviews + events and renders a summary. + +This avoids JSON overwrite races and keeps agent responsibilities auditable. + +## 6. Roles + +### Manager + +The Manager coordinates work but does not implement production code. + +Responsibilities: + +- read repo context and user goal, +- create a plan, +- split work into tasks, +- create task JSON files, +- generate worker prompts, +- manage board status, +- assign verification work to the reviewer, +- summarize worker/reviewer output, +- recommend merge/publish decisions for the user. + +Hard limits: + +- does not edit production code, +- does not merge, +- does not push, +- does not publish. + +### Worker + +Workers implement assigned tasks inside isolated boundaries. + +Responsibilities: + +- work only on the assigned task, +- stay within `allowedFiles`, +- avoid all `forbiddenFiles`, +- use TDD or the provided implementation plan, +- run verification commands when possible, +- write a report file, +- report blockers clearly. + +Hard limits: + +- does not merge, +- does not push, +- does not edit unrelated files, +- does not write shared `board.json`. + +### Reviewer / Debugger + +The Reviewer validates worker output. + +Responsibilities: + +- do not blindly trust worker reports, +- inspect changed files and diffs, +- check forbidden file touches, +- check scope creep, +- review test output, +- rerun or recommend verification where needed, +- return `PASS`, `REQUEST_CHANGES`, or `BLOCK`, +- suggest `diagnose` when debugging is needed. + +Hard limits: + +- does not implement production features, +- does not merge, +- does not push, +- does not publish. + +## 7. Task Schema + +Example task file: + +```json +{ + "id": "task-001", + "title": "Short task title", + "status": "todo", + "assignedRole": "worker-a", + "dependsOn": [], + "targetWorktree": "../.cewp-worktrees///task-001", + "branch": "cewp/task-001", + "mission": "Precise implementation mission.", + "allowedFiles": [], + "forbiddenFiles": [ + ".env", + "config/api_keys.json" + ], + "verification": [], + "outputContract": { + "summary": true, + "changedFiles": true, + "commandsRun": true, + "tests": true, + "risks": true, + "handoff": true + } +} +``` + +Allowed status values: + +- `todo` +- `claimed` +- `in_progress` +- `blocked` +- `ready_for_review` +- `review_failed` +- `approved` +- `merged` +- `done` + +Status ownership should be explicit in the final design. For v0.2, prefer Manager/CLI-controlled status transitions instead of arbitrary worker writes to `board.json`. + +## 8. Worktree Strategy + +Parallel workers must not work in the same working tree. + +v0.2 should document worktree guidance and generate worktree target paths, but automatic worktree creation can wait until v0.3. + +Default worktree recommendation: + +```txt +../.cewp-worktrees//// +``` + +Why this location: + +- repo runtime state stays inside `.cewp/`, +- worker working directories stay outside the main repo, +- diffs, reviews, and merges stay cleaner, +- ignored runtime files do not become nested worktree clutter, +- Windows paths with spaces remain manageable when quoted. + +v0.2 may print suggested commands, but should not create worktrees unless that scope is explicitly approved later. + +## 9. CLI Design For v0.2 + +MVP commands: + +```bash +cewp run init --workers 2 --reviewer +cewp run status +cewp run prompts +cewp run prompt manager +cewp run prompt worker-a +cewp run prompt worker-b +cewp run prompt reviewer +``` + +Command behavior: + +- `cewp run init --workers 2 --reviewer` + - creates a new `.cewp/runs//` folder, + - writes initial `run.json`, `board.json`, `plan.md`, + - creates role files, prompt files, task/report/review folders, + - prints the run id and next commands. + +- `cewp run status` + - finds the current/latest run, + - reads board, task files, reports, reviews, and events, + - prints task status, role status, missing reports, and review state. + +- `cewp run prompts` + - prints all role prompt paths and recommended Warp pane mapping, + - may optionally print prompt text or concise paste instructions. + +- `cewp run prompt manager` + - prints only the manager prompt. + +- `cewp run prompt worker-a` + - prints only the worker A prompt. + +- `cewp run prompt worker-b` + - prints only the worker B prompt. + +- `cewp run prompt reviewer` + - prints only the reviewer prompt. + +Avoid `cewp run start` in v0.2 because "start" implies process spawning. v0.2 is manual multi-pane coordination, not autonomous execution. + +## 10. Warp Multi-Pane Manual Flow + +User flow: + +1. In the repo: + +```bash +cewp run init --workers 2 --reviewer +``` + +2. Open four Warp panes: + +```txt +Pane 1: Manager Codex +Pane 2: Worker A Codex +Pane 3: Worker B Codex +Pane 4: Reviewer Codex +``` + +3. Generate prompts: + +```bash +cewp run prompts +``` + +4. Paste each role prompt into the matching Codex session. + +5. Agents communicate by reading and writing files under: + +```txt +.cewp/runs// +``` + +6. Workers produce reports. Reviewer validates them. Manager summarizes next actions. + +7. The user manually decides whether to merge, publish, or continue. + +## 11. v0.2 MVP Scope + +v0.2 should include: + +- `.cewp/runs` local runtime standard, +- `cewp run init`, +- role prompt generation, +- `cewp run status`, +- board/task/report/review schemas, +- README Coordinator Mode section, +- `docs/install.md` note for `.cewp/`, +- `.cewp/` gitignore rule, +- no npm publish until local tests and manual pilot pass. + +v0.2 should not change the existing 10 skills. + +## 12. v0.3 / v0.4 / v0.5 Roadmap + +### v0.3 + +- worktree helper commands, +- `cewp run worktrees plan`, +- `cewp run worktrees create`, +- `cewp run collect`, +- better conflict preflight, +- optional run selection by id. + +### v0.4 + +- optional adapter design, +- `codex exec` adapter research, +- `claude -p` adapter research, +- structured output capture, +- still no auto merge. + +### v0.5 + +- reviewer gate, +- controlled merge assistant, +- conflict detection, +- forbidden file detector, +- test verification summarizer, +- stronger PASS/BLOCK reporting. + +### v1.0 + +- semi-auto project manager, +- auto plan + auto task + auto review, +- manual merge/publish gate, +- durable audit trail for long-running multi-agent workflows. + +## 13. Risks + +Known risks: + +- token cost can rise quickly with 3-5 active agents, +- stale state if agents read old files, +- JSON overwrite if shared files become multi-writer, +- same-file conflicts across parallel workers, +- weak reviewer accepting bad changes, +- manager creating a wrong plan and spreading it to workers, +- Windows path quoting issues, +- worktree path confusion, +- agent scope creep, +- hidden secret/config file touches, +- false PASS reports, +- test environment drift between worktrees, +- dev server port collisions, +- reports becoming too verbose to be useful. + +## 14. Open Questions + +Open product/design questions: + +- Should the command namespace be `cewp run` or `cewp coord`? +- Should v0.2 include worktree commands or only worktree guidance? +- Should `.cewp/` be completely ignored by git? +- Should run history be retained by default? +- Should prompts be written as files only, printed to stdout, or both? +- How should Manager board-write authority be constrained? +- Is a task lock mechanism needed in v0.2? +- Should `cewp run status` pick the latest run automatically or require `--run `? +- Should worker report templates be strict markdown or JSON plus markdown? +- Should reviewer decisions be written as one file per task or one consolidated report? + +## 15. First Task For Next Codex Chat + +Use this prompt in the next clean Codex chat: + +```txt +We are continuing Codex Engineering Workflow Pack. + +Repo: + + +Task: +Start CEWP Coordinator Mode v0.2 planning. + +Rules: +- Create a new branch named feat/coordinator-mode. +- First read docs/coordinator-mode-roadmap.md. +- Do not edit existing skill contents. +- Do not touch .agents/skills except to inspect if needed. +- Do not publish npm. +- Do not bump version yet. +- Do not create a GitHub release. +- Do not bring back internal/private docs. +- Do not implement process spawning. +- Do not auto-merge or auto-push. + +Goal: +Produce an implementation plan for v0.2 MVP: +- .cewp/runs runtime structure +- cewp run init +- cewp run status +- cewp run prompts +- cewp run prompt +- schema files and prompt templates +- README/docs updates +- .cewp gitignore rule +- local verification commands + +After the plan, stop and ask for approval before CLI implementation. +``` + From c9a749f54dd5be7995f4c971190b82097f94c6b9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tuncay=20=C3=96lmez?= Date: Thu, 28 May 2026 22:21:54 +0300 Subject: [PATCH 2/3] feat: add coordinator mode cli skeleton --- .gitignore | 3 + README.md | 58 ++++ bin/cewp.js | 704 +++++++++++++++++++++++++++++++++++++++++++++++- docs/install.md | 22 ++ 4 files changed, 785 insertions(+), 2 deletions(-) diff --git a/.gitignore b/.gitignore index 825061d..80c8632 100644 --- a/.gitignore +++ b/.gitignore @@ -31,6 +31,9 @@ tmp/ temp/ .cache/ +# CEWP local runtime state +.cewp/ + # Local env and secrets .env .env.* diff --git a/README.md b/README.md index 856291b..6fab2ca 100644 --- a/README.md +++ b/README.md @@ -88,6 +88,64 @@ Planned CLI commands: - interactive mode - symlink/shared setup +## Coordinator Mode + +Coordinator Mode is a v0.2 CLI skeleton for manual multi-pane orchestration. It helps a Manager Codex, Worker Codex sessions, and a Reviewer/Debugger Codex coordinate through local files while the user stays in control. + +Start a local run: + +```bash +cewp run init --workers 2 --reviewer +``` + +Then open Warp or another terminal with separate panes: + +```txt +Pane 1: Manager Codex +Pane 2: Worker A Codex +Pane 3: Worker B Codex +Pane 4: Reviewer Codex +``` + +Print prompt locations and paste commands: + +```bash +cewp run prompts +cewp run prompt manager +cewp run prompt worker-a +cewp run prompt worker-b +cewp run prompt reviewer +``` + +Check the latest run: + +```bash +cewp run status +``` + +Runtime state lives under: + +```txt +.cewp/runs// +``` + +This directory is local runtime state and should not be committed. `board.json` is Manager/CLI-owned, not a multi-writer file. Workers read board/tasks and write only their own report and event files. The reviewer writes only review files and its own event log. + +v0.2 non-goals: + +- no Codex process spawning, +- no terminal input automation, +- no auto merge, +- no auto push, +- no same-working-tree parallel worker edits, +- no automatic worktree creation. + +Parallel workers must not edit the same working tree. v0.2 only recommends worktree paths such as: + +```txt +../.cewp-worktrees//// +``` + ## Install Modes ### Repo Install diff --git a/bin/cewp.js b/bin/cewp.js index 7022ce9..9e46d59 100644 --- a/bin/cewp.js +++ b/bin/cewp.js @@ -24,10 +24,15 @@ Usage: cewp init [--mode repo|global] [--target ] [--force] cewp list [--mode repo|global] [--target ] cewp doctor [--mode repo|global] [--target ] + cewp run init --workers --reviewer + cewp run status + cewp run prompts + cewp run prompt cewp --help Defaults: repo mode defaults to the current working directory when --target is omitted + run commands default to the current working directory and latest run Examples: cewp init @@ -38,17 +43,25 @@ Examples: cewp init --mode global --force cewp list cewp doctor --mode repo --target "/path/to/repo" + cewp run init --workers 2 --reviewer + cewp run status + cewp run prompts + cewp run prompt manager `); } function parseArgs(argv) { const args = { command: argv[0], + subcommand: argv[1], + role: argv[2], mode: "repo", target: undefined, targetProvided: false, force: false, help: false, + workers: undefined, + reviewer: false, }; if (argv[0] === "--help" || argv[0] === "-h") { @@ -57,9 +70,16 @@ function parseArgs(argv) { return args; } - for (let index = 1; index < argv.length; index += 1) { + const optionStart = args.command === "run" ? 2 : 1; + + for (let index = optionStart; index < argv.length; index += 1) { const arg = argv[index]; + if (args.command === "run" && args.subcommand === "prompt" && index === 2) { + args.role = arg; + continue; + } + if (arg === "--help" || arg === "-h") { args.help = true; continue; @@ -91,12 +111,687 @@ function parseArgs(argv) { continue; } + if (args.command === "run" && arg === "--workers") { + const value = argv[index + 1]; + if (!value || value.startsWith("--")) { + throw new Error("cewp run init --workers 2 --reviewer is the supported v0.2 shape."); + } + if (!/^\d+$/.test(value)) { + throw new Error("cewp run init --workers 2 --reviewer is the supported v0.2 shape."); + } + args.workers = Number.parseInt(value, 10); + index += 1; + continue; + } + + if (args.command === "run" && arg === "--reviewer") { + args.reviewer = true; + continue; + } + throw new Error(`Unknown argument: ${arg}`); } return args; } +function formatRunId(date = new Date()) { + const pad = (value) => String(value).padStart(2, "0"); + const year = date.getFullYear(); + const month = pad(date.getMonth() + 1); + const day = pad(date.getDate()); + const hour = pad(date.getHours()); + const minute = pad(date.getMinutes()); + const second = pad(date.getSeconds()); + return `${year}${month}${day}-${hour}${minute}${second}`; +} + +function roleLabel(role) { + if (role === "manager") { + return "Manager"; + } + + if (role === "reviewer") { + return "Reviewer"; + } + + const workerMatch = role.match(/^worker-([a-z])$/); + if (workerMatch) { + return `Worker ${workerMatch[1].toUpperCase()}`; + } + + return role; +} + +function getWorkerRoles(count) { + if (count !== 2) { + throw new Error("cewp run init --workers 2 --reviewer is the supported v0.2 shape."); + } + + return Array.from({ length: count }, (_, index) => { + const suffix = String.fromCharCode("a".charCodeAt(0) + index); + return `worker-${suffix}`; + }); +} + +function getRunRoot(runId, repoRoot = process.cwd()) { + return path.join(path.resolve(repoRoot), ".cewp", "runs", runId); +} + +function getRunsRoot(repoRoot = process.cwd()) { + return path.join(path.resolve(repoRoot), ".cewp", "runs"); +} + +function writeJson(filePath, value) { + fs.writeFileSync(`${filePath}`, `${JSON.stringify(value, null, 2)}\n`); +} + +function readJsonIfExists(filePath) { + if (!fs.existsSync(filePath)) { + return undefined; + } + + return JSON.parse(fs.readFileSync(filePath, "utf8")); +} + +function listFiles(directory, extension) { + if (!fs.existsSync(directory)) { + return []; + } + + return fs + .readdirSync(directory) + .filter((name) => name.endsWith(extension)) + .sort() + .map((name) => path.join(directory, name)); +} + +function findLatestRun(repoRoot = process.cwd()) { + const runsRoot = getRunsRoot(repoRoot); + + if (!fs.existsSync(runsRoot)) { + throw new Error(`No CEWP runs found. Missing directory: ${runsRoot}`); + } + + const runIds = fs + .readdirSync(runsRoot, { withFileTypes: true }) + .filter((entry) => entry.isDirectory()) + .map((entry) => entry.name) + .sort(); + + if (runIds.length === 0) { + throw new Error(`No CEWP runs found under: ${runsRoot}`); + } + + const runId = runIds[runIds.length - 1]; + return { + runId, + runRoot: path.join(runsRoot, runId), + }; +} + +function makePlanTemplate(runId) { + return `# CEWP Coordinator Run Plan + +Run ID: ${runId} + +## Goal + +Describe the user goal for this coordinated run. + +## Manager Plan + +- Define isolated tasks. +- Assign each task to one worker. +- Keep board.json Manager/CLI-owned. +- Send completed worker output through the reviewer gate. + +## Task Schema + +\`\`\`json +{ + "schemaVersion": 1, + "id": "task-001", + "title": "Short task title", + "status": "todo", + "assignedRole": "worker-a", + "dependsOn": [], + "targetWorktree": "../.cewp-worktrees///task-001", + "branch": "cewp/task-001", + "mission": "Precise implementation mission.", + "allowedFiles": [], + "forbiddenFiles": [".env", "config/api_keys.json"], + "verification": [], + "outputContract": { + "summary": true, + "changedFiles": true, + "commandsRun": true, + "tests": true, + "risks": true, + "handoff": true + } +} +\`\`\` + +Allowed task statuses: todo, claimed, in_progress, blocked, ready_for_review, review_failed, approved, merged, done. + +## Worktree Guidance + +v0.2 does not create worktrees automatically. Parallel workers must not edit the same working tree. + +Recommended path: + +\`\`\`txt +../.cewp-worktrees//// +\`\`\` +`; +} + +function makeAgentFile(role, runId) { + return `# ${roleLabel(role)} + +Run ID: ${runId} +Role: ${role} + +Use the matching prompt under prompts/ when starting this Codex session. +`; +} + +function makeManagerPrompt({ runId, runRoot, repoRoot, workers }) { + return `# CEWP Coordinator Mode - Manager Prompt + +You are the Manager Codex for CEWP run ${runId}. + +Repo root: +${repoRoot} + +Run root: +${runRoot} + +Your mission: +- Read the repo context and the user's goal. +- Produce a concise plan in plan.md. +- Split work into isolated task JSON files under tasks/. +- Update board.json as the Manager-owned coordination board. +- Define each task's allowedFiles and forbiddenFiles boundaries. +- Ask the Reviewer to gate worker output before any merge decision. + +Hard rules: +- Do not edit production code. +- board.json may be written only by Manager/CLI. +- Workers may read board.json and tasks/*.json but must not write board.json. +- Do not merge. +- Do not push. +- Do not publish. +- Do not spawn Codex processes. +- Do not automate terminal input. +- Do not create worktrees automatically in v0.2. + +Workers for this run: +${workers.map((worker) => `- ${worker}`).join("\n")} + +Task schema to use: + +\`\`\`json +{ + "schemaVersion": 1, + "id": "task-001", + "title": "Short task title", + "status": "todo", + "assignedRole": "worker-a", + "dependsOn": [], + "targetWorktree": "../.cewp-worktrees///task-001", + "branch": "cewp/task-001", + "mission": "Precise implementation mission.", + "allowedFiles": [], + "forbiddenFiles": [".env", "config/api_keys.json"], + "verification": [], + "outputContract": { + "summary": true, + "changedFiles": true, + "commandsRun": true, + "tests": true, + "risks": true, + "handoff": true + } +} +\`\`\` + +Allowed task statuses: +todo, claimed, in_progress, blocked, ready_for_review, review_failed, approved, merged, done. + +Worktree guidance: +- v0.2 only recommends worktree paths. +- Parallel workers must not work in the same working tree. +- Recommended path: ../.cewp-worktrees//${runId}// +`; +} + +function makeWorkerPrompt({ runId, runRoot, repoRoot, role }) { + return `# CEWP Coordinator Mode - ${roleLabel(role)} Prompt + +You are ${roleLabel(role)} for CEWP run ${runId}. + +Repo root: +${repoRoot} + +Run root: +${runRoot} + +Your mission: +- Work only on the task assigned to ${role}. +- Read board.json and tasks/*.json. +- Follow the task mission, allowedFiles, forbiddenFiles, and verification list. +- Run verification commands when possible. +- Write your report to reports/${role}-report.md. +- Append your events to events/${role}.jsonl. + +Hard rules: +- Do not write board.json. +- Do not edit tasks/*.json unless the Manager explicitly changes the run design. +- Do not work outside your assigned task. +- Do not edit files outside allowedFiles when allowedFiles is non-empty. +- Do not touch forbiddenFiles. +- Do not merge. +- Do not push. +- Do not publish. +- Do not spawn Codex processes. +- Do not automate terminal input. +- Do not work in the same working tree as another parallel worker. + +Report template: + +\`\`\`md +# Worker Report + +Role: ${role} +Task: +Status: + +## Summary + +## Changed Files + +## Commands Run + +## Test Results + +## Risks + +## Handoff Notes +\`\`\` + +Event JSONL guidance: +- Append one JSON object per line to events/${role}.jsonl. +- Include at least timestamp, role, event, and optional task id. +`; +} + +function makeReviewerPrompt({ runId, runRoot, repoRoot }) { + return `# CEWP Coordinator Mode - Reviewer Prompt + +You are the Reviewer/Debugger Codex for CEWP run ${runId}. + +Repo root: +${repoRoot} + +Run root: +${runRoot} + +Your mission: +- Review worker output without blindly trusting worker reports. +- Inspect changed files, diffs, test output, forbidden file touches, and scope creep. +- Read board.json, tasks/*.json, reports/*.md, and relevant git output. +- Write your review to reviews/reviewer-report.md. +- Append your events to events/reviewer.jsonl. + +Hard rules: +- Do not implement production features. +- Do not write board.json. +- Do not write worker reports. +- Do not merge. +- Do not push. +- Do not publish. +- Do not spawn Codex processes. +- Do not automate terminal input. + +Decision format: + +\`\`\`md +# Reviewer Report + +Decision: PASS | REQUEST_CHANGES | BLOCK + +## Scope Check + +## Forbidden File Check + +## Diff Review + +## Verification + +## Required Changes + +## Notes +\`\`\` +`; +} + +function runInit(options) { + if (options.subcommand !== "init") { + throw new Error(`Unsupported run command: ${options.subcommand || "(missing)"}`); + } + + const workers = getWorkerRoles(options.workers); + + if (!options.reviewer) { + throw new Error("cewp run init currently requires --reviewer for v0.2."); + } + + const repoRoot = path.resolve(process.cwd()); + const runId = formatRunId(); + const runRoot = getRunRoot(runId, repoRoot); + + if (fs.existsSync(runRoot)) { + throw new Error(`Run already exists: ${runRoot}`); + } + + const directories = [ + runRoot, + path.join(runRoot, "events"), + path.join(runRoot, "agents"), + path.join(runRoot, "tasks"), + path.join(runRoot, "reports"), + path.join(runRoot, "reviews"), + path.join(runRoot, "prompts"), + path.join(runRoot, "handoff"), + ]; + + for (const directory of directories) { + fs.mkdirSync(directory, { recursive: true }); + } + + const roles = ["manager", ...workers, "reviewer"]; + const runJson = { + schemaVersion: 1, + runId, + createdAt: new Date().toISOString(), + repoRoot, + workers, + reviewer: "reviewer", + status: "planning", + }; + const boardJson = { + schemaVersion: 1, + runId, + managerOwnsBoard: true, + status: "planning", + tasks: [], + roles: Object.fromEntries( + roles.map((role) => [role, { status: role === "manager" ? "active" : "waiting" }]), + ), + }; + + writeJson(path.join(runRoot, "run.json"), runJson); + writeJson(path.join(runRoot, "board.json"), boardJson); + fs.writeFileSync(path.join(runRoot, "plan.md"), makePlanTemplate(runId)); + + for (const role of roles) { + fs.writeFileSync(path.join(runRoot, "agents", `${role}.md`), makeAgentFile(role, runId)); + fs.writeFileSync(path.join(runRoot, "events", `${role}.jsonl`), ""); + } + + fs.writeFileSync( + path.join(runRoot, "prompts", "manager-prompt.md"), + makeManagerPrompt({ runId, runRoot, repoRoot, workers }), + ); + + for (const role of workers) { + fs.writeFileSync( + path.join(runRoot, "prompts", `${role}-prompt.md`), + makeWorkerPrompt({ runId, runRoot, repoRoot, role }), + ); + } + + fs.writeFileSync( + path.join(runRoot, "prompts", "reviewer-prompt.md"), + makeReviewerPrompt({ runId, runRoot, repoRoot }), + ); + + console.log("CEWP Coordinator Mode run initialized"); + console.log(`Run ID: ${runId}`); + console.log(`Run root: ${runRoot}`); + console.log(""); + console.log("Next commands:"); + console.log(" cewp run prompts"); + console.log(" cewp run status"); +} + +function getTaskStatusCounts(tasks) { + return tasks.reduce((counts, task) => { + const status = task.status || "unknown"; + counts[status] = (counts[status] || 0) + 1; + return counts; + }, {}); +} + +function readEvents(filePath) { + if (!fs.existsSync(filePath)) { + return []; + } + + const lines = fs + .readFileSync(filePath, "utf8") + .split(/\r?\n/) + .map((line) => line.trim()) + .filter(Boolean); + + if (lines.length === 0) { + return []; + } + + return lines.map((line, index) => { + const event = { + order: index, + lineOrder: index, + filePath, + }; + + try { + const parsed = JSON.parse(line); + return { + ...event, + value: parsed, + timeMs: getEventTimeMs(parsed), + }; + } catch { + return { + ...event, + value: line, + timeMs: undefined, + }; + } + }); +} + +function getEventTimeMs(event) { + if (!event || typeof event !== "object") { + return undefined; + } + + const value = event.timestamp || event.time; + if (!value) { + return undefined; + } + + const timeMs = Date.parse(value); + return Number.isNaN(timeMs) ? undefined : timeMs; +} + +function getFileMtimeMs(filePath) { + try { + return fs.statSync(filePath).mtimeMs; + } catch { + return 0; + } +} + +function chooseLatestEvent(entries) { + if (entries.length === 0) { + return undefined; + } + + return entries + .map((entry, index) => ({ + ...entry, + fallbackMs: getFileMtimeMs(entry.filePath), + readOrder: index, + })) + .sort((left, right) => { + const leftTime = left.event.timeMs; + const rightTime = right.event.timeMs; + + if (leftTime !== undefined || rightTime !== undefined) { + return (leftTime || 0) - (rightTime || 0); + } + + if (left.fallbackMs !== right.fallbackMs) { + return left.fallbackMs - right.fallbackMs; + } + + if (left.lineOrder !== right.lineOrder) { + return left.lineOrder - right.lineOrder; + } + + return left.readOrder - right.readOrder; + }) + .at(-1); +} + +function runStatus() { + const { runId, runRoot } = findLatestRun(); + const runJson = readJsonIfExists(path.join(runRoot, "run.json")); + const boardJson = readJsonIfExists(path.join(runRoot, "board.json")); + const taskFiles = listFiles(path.join(runRoot, "tasks"), ".json"); + const tasks = taskFiles.map((filePath) => readJsonIfExists(filePath)).filter(Boolean); + const reportFiles = listFiles(path.join(runRoot, "reports"), ".md"); + const reviewFiles = listFiles(path.join(runRoot, "reviews"), ".md"); + const eventFiles = listFiles(path.join(runRoot, "events"), ".jsonl"); + const statusCounts = getTaskStatusCounts(tasks); + const lastEvents = eventFiles + .flatMap((filePath) => readEvents(filePath).map((event) => ({ filePath, event }))); + const lastEvent = chooseLatestEvent(lastEvents); + + console.log("CEWP Coordinator Mode status"); + console.log(`Run ID: ${runId}`); + console.log(`Run root: ${runRoot}`); + console.log(`Run status: ${(runJson && runJson.status) || (boardJson && boardJson.status) || "unknown"}`); + console.log(""); + console.log("Role status:"); + + const roles = (boardJson && boardJson.roles) || {}; + for (const role of Object.keys(roles).sort()) { + console.log(` ${role}: ${roles[role].status || "unknown"}`); + } + + if (Object.keys(roles).length === 0) { + console.log(" none"); + } + + console.log(""); + console.log(`Tasks: ${tasks.length}`); + + if (Object.keys(statusCounts).length === 0) { + console.log(" no task files found"); + } else { + for (const status of Object.keys(statusCounts).sort()) { + console.log(` ${status}: ${statusCounts[status]}`); + } + } + + console.log(""); + console.log(`Reports: ${reportFiles.length ? reportFiles.map((filePath) => path.basename(filePath)).join(", ") : "none"}`); + console.log(`Reviews: ${reviewFiles.length ? reviewFiles.map((filePath) => path.basename(filePath)).join(", ") : "none"}`); + console.log(""); + + if (lastEvent) { + console.log(`Last event file: ${path.basename(lastEvent.filePath)}`); + console.log(`Last event: ${typeof lastEvent.event.value === "string" ? lastEvent.event.value : JSON.stringify(lastEvent.event.value)}`); + } else { + console.log("Last event: none"); + } +} + +function runPrompts() { + const { runId, runRoot } = findLatestRun(); + const promptsRoot = path.join(runRoot, "prompts"); + + console.log("CEWP Coordinator Mode prompts"); + console.log(`Run ID: ${runId}`); + console.log(""); + console.log("Recommended Warp panes:"); + console.log(" Pane 1: Manager"); + console.log(" Pane 2: Worker A"); + console.log(" Pane 3: Worker B"); + console.log(" Pane 4: Reviewer"); + console.log(""); + console.log("Prompt commands:"); + console.log(` manager -> ${path.join(promptsRoot, "manager-prompt.md")}`); + console.log(" cewp run prompt manager"); + console.log(` worker-a -> ${path.join(promptsRoot, "worker-a-prompt.md")}`); + console.log(" cewp run prompt worker-a"); + console.log(` worker-b -> ${path.join(promptsRoot, "worker-b-prompt.md")}`); + console.log(" cewp run prompt worker-b"); + console.log(` reviewer -> ${path.join(promptsRoot, "reviewer-prompt.md")}`); + console.log(" cewp run prompt reviewer"); +} + +function runPrompt(role) { + const supportedRoles = ["manager", "worker-a", "worker-b", "reviewer"]; + + if (!supportedRoles.includes(role)) { + throw new Error(`Unsupported run prompt role: ${role || "(missing)"}. Supported roles: ${supportedRoles.join(", ")}.`); + } + + const { runRoot } = findLatestRun(); + const promptFile = path.join(runRoot, "prompts", `${role}-prompt.md`); + + if (!fs.existsSync(promptFile)) { + throw new Error(`Prompt file not found for ${role}: ${promptFile}`); + } + + process.stdout.write(fs.readFileSync(promptFile, "utf8")); +} + +function runCommand(options) { + if (options.help || !options.subcommand) { + usage(); + return; + } + + if (options.subcommand === "init") { + runInit(options); + return; + } + + if (options.subcommand === "status") { + runStatus(); + return; + } + + if (options.subcommand === "prompts") { + runPrompts(); + return; + } + + if (options.subcommand === "prompt") { + runPrompt(options.role); + return; + } + + throw new Error(`Unsupported run command: ${options.subcommand}`); +} + function copySkill(sourceSkill, targetSkill, force) { if (fs.existsSync(targetSkill) && !force) { return "skipped"; @@ -269,7 +964,12 @@ function main() { return; } - if (!["init", "list", "doctor"].includes(args.command)) { + if (args.command === "run") { + runCommand(args); + return; + } + + if (!["init", "list", "doctor", "run"].includes(args.command)) { throw new Error(`Unsupported command: ${args.command}`); } } catch (error) { diff --git a/docs/install.md b/docs/install.md index 2ffe792..3d007e6 100644 --- a/docs/install.md +++ b/docs/install.md @@ -67,6 +67,28 @@ Planned commands: - interactive mode - symlink/shared setup +## Coordinator Mode Runtime + +Coordinator Mode is separate from installing the 10 workflow skills. Skill install copies reusable Codex instructions into `.agents/skills/`; Coordinator Mode creates local runtime files for a manual multi-pane coordination session. + +Start a local coordination run from a repo: + +```bash +cewp run init --workers 2 --reviewer +cewp run prompts +cewp run status +``` + +Runtime state is written under: + +```txt +.cewp/runs// +``` + +This folder contains local board, task, prompt, report, review, event, and handoff files. It is not package content and should not be committed. Add `.cewp/` to the project `.gitignore` for repos that use Coordinator Mode. + +Coordinator Mode v0.2 is manual orchestration only. It does not spawn Codex processes, automate terminal input, merge, push, publish, or create worktrees. + ## Repo Sharing vs Local-only If `.agents/skills/` should be shared with the project or team, commit it to the repo. From 5f77b89a72bd3eea26de9db3b87876e68fa95e0c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tuncay=20=C3=96lmez?= Date: Thu, 28 May 2026 22:33:27 +0300 Subject: [PATCH 3/3] fix: clarify coordinator run status output --- bin/cewp.js | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/bin/cewp.js b/bin/cewp.js index 9e46d59..816ee7b 100644 --- a/bin/cewp.js +++ b/bin/cewp.js @@ -685,7 +685,8 @@ function runStatus() { console.log("CEWP Coordinator Mode status"); console.log(`Run ID: ${runId}`); console.log(`Run root: ${runRoot}`); - console.log(`Run status: ${(runJson && runJson.status) || (boardJson && boardJson.status) || "unknown"}`); + console.log(`Run status: ${(runJson && runJson.status) || "unknown"}`); + console.log(`Board status: ${(boardJson && boardJson.status) || "unknown"}`); console.log(""); console.log("Role status:"); @@ -728,6 +729,7 @@ function runPrompts() { console.log("CEWP Coordinator Mode prompts"); console.log(`Run ID: ${runId}`); + console.log("Paste each prompt into its matching Warp pane."); console.log(""); console.log("Recommended Warp panes:"); console.log(" Pane 1: Manager");