{
  "markdown": "# parallel-plan-executor\n\n*[Leer esto en español](README.es.md)*\n\nA Claude Code `Workflow` that executes a `cys:plan` implementation plan, running\nindependent tasks in parallel via a dependency DAG inferred from each task's\n`Consumes`/`Produces` block — instead of one task at a time like sequential plan\nexecutors do.\n\nThe **generated code** is technology-agnostic — validated against both Node and\nJava/Spring Boot projects, nothing in the design is tied to a specific language.\n\n## Table of contents\n\n- [What is cys?](#what-is-cys)\n- [See it in action (60 seconds)](#see-it-in-action-60-seconds)\n- [Quick Start](#quick-start)\n- [Installing the cys plugin](#installing-the-cys-plugin)\n- [One-time permissions setup (merges)](#one-time-permissions-setup-merges)\n- [Using cys](#using-cys)\n- [Building from source](#building-from-source)\n- [How it works](#how-it-works)\n- [Safety checks & known limitations](#safety-checks--known-limitations)\n- [Reporting bugs & contributing](#reporting-bugs--contributing)\n\n## What is cys?\n\n**cys** is two things, sharing one repo:\n\n1. **A portable plugin** — five skills covering the whole flow\n   **design → plan → run → check → ship**, created by Christian Bacilio and named\n   after his twin daughters, **Cielo y Sophia**. Four of the five skills are plain\n   Markdown with no Claude-Code-specific coupling, so the same `skills/` directory\n   works as-is on Claude Code, Cursor, and Gemini CLI — see\n   [Installing the cys plugin](#installing-the-cys-plugin).\n2. **`cys:run`, the parallel execution engine** (this repo's `Workflow` script) —\n   the actual differentiator, and **Claude Code only**. It's a `Workflow` script,\n   a third kind of Claude Code extension distinct from plugins and skills: you\n   invoke it by absolute path (`scriptPath: <clone>/workflows/parallel-plan-executor.js`),\n   it can't pause mid-run to ask you anything, and everything it produces —\n   task briefs, review verdicts, `.cys/handoff.md` — is written to disk instead.\n\n| Skill | What it does |\n|---|---|\n| `cys:design` | idea → spec |\n| `cys:plan` | spec → implementation plan |\n| `cys:run` | this repo's `Workflow` — launched via `/cys:run-plan` or `/cys:flow`. **Claude Code only.** |\n| `cys:check` | adversarial review / verification |\n| `cys:ship` | commit / SemVer bump / PR |\n| `cys:guide` | index — which skill to use when |\n\n`/cys:flow` (Claude Code only) is the all-in-one entry point: give it a target\nrepo and an idea, and it walks the whole flow (design → plan → parallel run) with\nyour approval gates at each stage. Use `/cys:run-plan` instead when an approved\nplan already exists.\n\nDesign spec: `docs/cys/specs/2026-07-04-parallel-plan-executor-design.md`.\n\n```mermaid\nflowchart TD\n    subgraph DESIGN[\"1 · cys:design\"]\n        D1[\"User's idea\"]\n        D2[\"Dialogue: context,\\none question at a time,\\n2-3 approaches\"]\n        D3[\"docs/cys/specs/*.md\"]\n        D1 --> D2 --> D3\n    end\n\n    GATE1{\"Human gate:\\ndoes the user\\napprove the spec?\"}\n    D3 --> GATE1\n    GATE1 -- \"no, revise\" --> D2\n    GATE1 -- \"yes\" --> PLAN\n\n    subgraph PLAN[\"2 · cys:plan\"]\n        P1[\"Numbered tasks\\nFiles + Consumes/Produces\"]\n        P2[\"docs/cys/plans/*.md\"]\n        P3[\"bin/parse-plan.js\\ngraph dry-run\"]\n        P1 --> P2 --> P3\n    end\n\n    PLAN --> RUN\n\n    subgraph RUN[\"3 · cys:run (Claude Code only)\"]\n        R1[\"DAG inferred from the plan\"]\n        R2[\"worktree + implement + adversarial\\nreview + serialized merge,\\nper task, in parallel where\\nthe DAG allows it\"]\n        R3[\"merged task-&lt;id&gt; branches\\n+ .cys/ (briefs, reports, diffs)\"]\n        R1 --> R2 --> R3\n    end\n\n    RUN --> CHECK\n\n    subgraph CHECK[\"4 · cys:check (optional)\"]\n        C1[\"Extra review on a\\nbranch that's ready\"]\n        C2[\"Verdicts + findings\\nto .cys/pending.md\"]\n        C1 --> C2\n    end\n\n    CHECK --> SHIP\n    RUN -.-> SHIP\n\n    subgraph SHIP[\"5 · cys:ship\"]\n        S1[\"Classifies the change,\\ncomputes SemVer\"]\n        S2[\"CHANGELOG + branch +\\ncommit + PR\"]\n        S1 --> S2\n    end\n\n    GATE2{\"Human gate:\\ndoes the user\\nmerge the PR?\"}\n    S2 --> GATE2\n    GATE2 -- \"yes\" --> DONE[\"Change integrated\"]\n\n    style GATE1 fill:#8a6d1a,color:#fff\n    style GATE2 fill:#8a6d1a,color:#fff\n    style DONE fill:#1a6b2a,color:#fff\n```\n\nSource: `docs/diagram/flujo-cys-ecosystem.mmd`.\n\n## See it in action (60 seconds)\n\nOne request, in plain language:\n\n> `/cys:flow ~/projects/persons-api \"A CRUD REST API for managing person records, Java 17 / Spring Boot 3, MongoDB persistence\"`\n\ncys turns that into a spec, a plan, and — the part that's actually\ndifferent from other AI coding tools — a real **parallel** execution.\nFrom a pilot run of exactly that idea:\n\n| Task | What it built | Ran |\n|---|---|---|\n| 1. Domain model & scaffolding | `Person` document, Maven project | alone — everything else depends on it (9m13s) |\n| 2. Repository | `PersonRepository` | **in parallel** with Task 3 (2m01s) |\n| 3. Service layer | business rules, validation | **in parallel** with Task 2 (1m46s) |\n| 4. Controller | REST endpoints | after 1–3 (2m11s) |\n| 5. Error handling | `GlobalExceptionHandler` | after 1 & 4 (2m56s) |\n\nTasks 2 and 3 don't depend on each other — cys inferred that from their\n`Consumes`/`Produces` blocks and ran them concurrently instead of one\nafter another. Every task went through its own isolated git worktree, an\nadversarial code review, and a serialized merge — you get a PR with a\nwhole-branch review verdict, not just green tests. See\n[Reporting bugs](#reporting-bugs--contributing) below if anything looks off — the\nfinal review already writes its own findings to `.cys/pending.md` for you.\n\n## Quick Start\n\nThe fast path, for Claude Code — no cloning, no building. Installing the\nplugin already materializes this whole repo (pre-built engine included)\nwhere Claude Code can run it:\n\n```\n/plugin marketplace add bacsystem/parallel-plan-executor\n/plugin install cys@bacsystem\n```\n\nThen, from any Claude Code session:\n\n> `/cys:flow /absolute/path/to/your-project \"describe what you want built\"`\n\nThat's the whole flow — design, plan, and (Claude Code only) a real\nparallel run — with your approval at each gate. See\n[Installing the cys plugin](#installing-the-cys-plugin) for Cursor and\nGemini CLI, and [Using cys](#using-cys) for the full first-run walkthrough\nonce you're past the quick version.\n\nOn other platforms (Cursor, Gemini CLI), the plugin gives you `cys:design`\nand `cys:plan`; `cys:guide` tells you how to execute the resulting plan's\ntasks yourself, since `cys:run`'s parallel engine is Claude Code only.\n\n## Installing the cys plugin\n\ncys's five non-engine skills (`design`, `plan`, `check`, `ship`, `guide`)\nare plain Markdown with no Claude-Code-specific coupling, so they're\nshared as-is — same `skills/` directory, no forked copy — across every\nplatform below. `cys:run` (parallel execution, the DAG scheduler,\nadversarial review, and serialized merging) is **Claude Code only**: on\nany other platform, `cys:guide` tells you how to execute a plan's tasks\nyourself once `cys:plan` has produced one.\n\n### Claude Code\n\nInstall from this repo's self-hosted marketplace:\n\n```\n/plugin marketplace add bacsystem/parallel-plan-executor\n/plugin install cys@bacsystem\n```\n\nThe first line resolves the short `owner/repo` GitHub form. Two equivalent\nalternatives, if you need them:\n\n```\n# Full GitHub URL instead of the short form\n/plugin marketplace add https://github.com/bacsystem/parallel-plan-executor\n\n# A local clone instead of GitHub (e.g. to test uncommitted changes)\n/plugin marketplace add /absolute/path/to/your/clone\n```\n\nInstalling the plugin also exposes this repo's `commands/run-plan.md` as the\n`/cys:run-plan` slash command, and `commands/flow.md` as `/cys:flow` — no\nmanual file copying needed.\n\n### Cursor\n\nCursor doesn't have a `/plugin marketplace add <repo>`-style command like\nClaude Code, but it does have a \"from a local repo\" install path in its\nown Settings UI (confirmed working — Cursor's plugin UI changed after\nthis section was first written, so trust these steps over any older\nscreenshot you find elsewhere):\n\n1. Clone this repo (see [Building from source](#building-from-source) below — for just\n   the skills, cloning is enough, you don't need to build the workflow\n   artifact or run its test suite).\n2. In Cursor: **Settings → Plugins** (or the **Customize** panel, if\n   your version has moved plugin management there) → **+ Add** →\n   **From Local Repo** → point it at your clone's absolute path.\n3. `cys` shows up under a \"Bacsystem\" group (from `plugin.json`'s\n   `author` field) with an **Add** button — click it. Once it says\n   **Added**, the skills are live, no reload needed.\n\nInvoke skills the same way you would any other Cursor skill (e.g.\n`/design`, `/plan`).\n\n<details>\n<summary>Fallback: symlink into Cursor's local plugins folder</summary>\n\nIf your Cursor version doesn't have the \"From Local Repo\" flow, the\nolder documented mechanism still works: link the clone into Cursor's\nlocal plugins folder (`~/.cursor/plugins/local/<name>` on macOS/Linux,\nper [Cursor's plugin docs](https://cursor.com/docs/plugins)). A symlink\nis preferred over a copy so future `git pull`s stay picked up — **always\nuse the clone's absolute path as the link target**, not a relative one\n(a relative target resolves against the symlink's own directory, not\nwherever you ran the command from, and silently breaks):\n\n**macOS / Linux:**\n```\nmkdir -p ~/.cursor/plugins/local\nln -s /absolute/path/to/your/clone ~/.cursor/plugins/local/cys\n```\n\n**Windows (PowerShell):**\n```powershell\nNew-Item -ItemType Directory -Force \"$env:USERPROFILE\\.cursor\\plugins\\local\" | Out-Null\nNew-Item -ItemType Junction -Path \"$env:USERPROFILE\\.cursor\\plugins\\local\\cys\" -Target \"C:\\absolute\\path\\to\\your\\clone\"\n```\nA junction (`New-Item -ItemType Junction`, or `mklink /J` from `cmd.exe`)\nworks without admin rights, unlike a regular directory symlink\n(`New-Item -ItemType SymbolicLink` / `mklink /D`), which needs either an\nelevated prompt or Developer Mode enabled.\n\nThen reload Cursor (Command Palette → \"Developer: Reload Window\") to\npick it up.\n</details>\n\n### Gemini CLI\n\nThe five non-engine skills (`design`, `plan`, `check`, `ship`, `guide`)\nalso work in [Gemini CLI](https://geminicli.com), via its native Agent\nSkills feature — no forked copy, `skills/` is discovered as-is by\ndirectory-name convention (no manifest field needed, unlike Cursor).\n\nInstall:\n\n```\ngemini extensions install https://github.com/bacsystem/parallel-plan-executor\n```\n\nThis clones the whole repo to `~/.gemini/extensions/cys/` and makes the\nskills available in every project — not just the one you ran the\ncommand from. Since install copies rather than tracks the repo live, run\n`gemini extensions update cys` to pick up future releases.\n\n`cys:run`'s parallel execution stays Claude-Code-only (see\n[Building from source](#building-from-source) below): on Gemini CLI,\n`cys:guide` tells you how to execute a plan's tasks yourself instead.\n\n## One-time permissions setup (merges)\n\nDo this once, before your first real `cys:run`, so task merges don't get\nblocked mid-run.\n\nThe workflow's merge agents run `git merge` inside your target repo. Claude\nCode treats an agent merging code as a sensitive action, and what happens\ndepends on your permission mode:\n\n- **Default (normal) mode**: nothing to configure. The first time a merge agent runs\n  `git merge`, you get Claude Code's native permission dialog — **Allow once / Allow\n  always / Deny**. Pick \"Allow always\" on the first one and the rest of the run flows\n  without asking again.\n- **Auto mode**: there is no dialog by default — an automatic classifier decides\n  alone, and it may block agent merges even when you authorized the run up front (see\n  the permissions note in [branching topology](#recommended-branching-topology) for\n  why). To get the same yes/no dialog as normal mode, add an **`ask` rule** to the\n  **target project's** `.claude/settings.json` (create the file if needed):\n\n```json\n{\n  \"permissions\": {\n    \"ask\": [\n      \"Bash(git merge:*)\",\n      \"Bash(git -C * merge *)\"\n    ]\n  }\n}\n```\n\nWith that rule in place, every `git merge` from any agent pauses and asks **you**,\ndeterministically, regardless of mode — you just click, never type. If you'd rather\nnever be asked, use `\"allow\"` instead of `\"ask\"` (the run becomes fully hands-off; the\nhuman gate moves to the final PR review).\n\n## Using cys\n\nThis section walks the full first-run experience, then covers the\nreference pieces (manual invocation, the `/run-plan` command, the\nHandoff phase, branch topology) for when you need more control than\n`/cys:flow` gives you.\n\n### Step-by-step guide (first time using this)\n\nThis subsection is for anyone who hasn't run the workflow before and wants to go\nthrough it without getting lost. If you already know it, [Manual\ninvocation](#manual-invocation-reference) below is the quick reference.\n\n#### Step 0 — What you need ready before starting\n\n- **An approved implementation plan**, with numbered tasks and their\n  `Consumes`/`Produces` blocks (the format produced by the `cys:plan` skill). If you\n  don't have one yet, ask Claude Code, from your project's repo: *\"help me write an\n  implementation plan for [your feature]\"* — with the cys plugin installed that runs\n  `cys:design` → `cys:plan` and leaves the plan file ready.\n- **The repo you're automating**, with a clean working tree (`git status` shows no\n  pending changes) and, if you'll request `openPr: true` at the end, a GitHub remote\n  already configured with `gh auth status` green.\n- The cys plugin installed (see [Quick Start](#quick-start)) — no manual cloning\n  needed for this path. If you're driving the engine directly instead of through the\n  plugin commands, see [Building from source](#building-from-source).\n\n#### Step 1 — Open a Claude Code session\n\nIt can be in your project's folder, in this repo's folder, or anywhere else — the\nworkflow doesn't depend on where your Claude Code session is running, as long as you\ngive it absolute paths to the plan and the target repo.\n\n#### Step 2 — Ask Claude Code in plain language\n\n**You don't need to hand-write the `args` JSON.** That's Claude Code's job: you just\ntell it what you want in a sentence, with these pieces of information:\n\n- the path to your plan (`planPath`),\n- the path to your target project (`repoPath`),\n- the name of the integration branch (`integrationBranch`) — an ephemeral feature branch\n  cut from `develop`, **never** `develop`/`main` directly (see the recommended topology\n  below),\n- whether you want it to push and open the PR at the end (`openPr`) and against which\n  branch (`pr.base`),\n- **your explicit authorization for the merges**, naming the branches — this matters,\n  see the box below.\n\nReal example (similar to what was used while building this very fix):\n\n> \"Launch the parallel-plan-executor workflow on my project at `D:/my-project`. The plan\n> is at `docs/plans/2026-07-16-my-feature.md`, already approved. Integration branch:\n> `feature/my-feature`. At the end, push and create the PR against `develop`. I\n> authorize merging branches task-1 through task-6.\"\n\nClaude Code takes care of running `bin/parse-plan.js` on your plan, building the `args`,\nand invoking the `Workflow` tool with this repo's script — you never touch JSON directly.\n\n> **Why name the branches in your authorization?** If the environment has Claude Code's\n> permission classifier in auto mode, it may require a human to explicitly authorize\n> merges — and that authorization needs to name the concrete action (\"merge task-1\n> through task-6\"), not a plain \"yes\" or \"go ahead\". Saying it upfront, with branches\n> named, avoids the run getting stuck partway through. See the permissions note in\n> [branching topology](#recommended-branching-topology) for the technical detail.\n\n#### Step 3 — What you'll see while it runs\n\nThe workflow runs in the background — it doesn't wait for your reply. You'll see:\n\n- A text progress bar like `[####----] 2/6 tasks settled` every time a task finishes\n  (merged, failed, or skipped).\n- A `Task N: started (implement)` notice as soon as each task starts, so you know it\n  isn't stuck during the minutes implementation takes.\n\nYou can ask Claude Code *\"how's the workflow going?\"* at any point — it will check the\nreal state and tell you which tasks finished, which are in progress, and whether\nanything went wrong. You can also open Claude Code's `/workflows` panel to see the\nper-phase detail (Implement, Review, Merge, Final review, Handoff), how many agents and\ntokens each phase used, and each agent's timing.\n\n#### Step 4 — If something gets stuck\n\nThe most common snag is a merge getting marked as blocked out of caution, **even after\nyou authorized upfront** — that's an environment safety measure, not a flaw in your\nplan. If that happens:\n\n1. Ask Claude Code what happened — it should be able to explain the concrete cause.\n2. Repeat your authorization naming the specific branches still pending (\"I authorize\n   merging task-2 and task-3\") and ask it to retry.\n3. The run is recoverable: nothing already done is lost. Tasks that already finished\n   (implemented, reviewed, merged) don't re-run — only what's still pending retries.\n\n#### Step 5 — When it finishes\n\n- If **at least one task merged**, you'll have a `.cys/handoff.md` file in\n  your project with: the suggested PR title and body, the proposed SemVer bump, and a\n  cleanup checklist (which `task-N` branches to delete and when) — see\n  [Handoff phase](#handoff-phase) for the full detail.\n- If you requested `openPr: true`, the PR is **already created** in GitHub against the\n  branch you specified — review it yourself and merge it whenever you're satisfied. The\n  workflow never merges the PR on its own; that decision always stays in your hands.\n- If any task failed or got blocked, the final report will tell you exactly which one\n  and why — and which other tasks were skipped in cascade because they depended on it.\n\n#### Common errors\n\n| What you see | What it means |\n|---|---|\n| `args.tasks must be a non-empty array` | The plan has no parseable tasks, or the plan wasn't parsed correctly. Check that your plan has `### Task N:` blocks with `Consumes`/`Produces`. |\n| A merge comes back `CONFLICT` with no real git conflict | Almost always the permission classifier asking for explicit authorization — see Step 4. |\n| The run stops partway through | It's recoverable: Claude Code can resume it without losing the work already done. |\n| The agent takes several minutes \"doing nothing\" when the first task starts | Normal — the first `implement` includes setting up the project's environment; you'll see the progress notice as soon as it's done. |\n\n### Manual invocation (reference)\n\nOnce you know the flow, this is the raw shape of what `/cys:flow`/`/cys:run-plan`\ndo for you — useful if you're scripting around cys or want to see every field:\n\n```bash\n# 1. Compute the task graph for your plan\n#    (stdout is pure JSON; ambiguity warnings — e.g. two tasks producing the same\n#    symbol — go to stderr and are also included in the JSON's \"warnings\" field)\nnode bin/parse-plan.js /path/to/your-plan.md > /tmp/plan-graph.json\n\n# 2. Ask Claude Code to invoke the Workflow tool with:\n#    scriptPath: \"<this repo>/workflows/parallel-plan-executor.js\"\n#    args: { tasks: <the \"tasks\" field of plan-graph.json>,\n#            graph: <the \"graph\" field of plan-graph.json>,\n#            planPath: \"/path/to/your-plan.md\",\n#            repoPath: \"/path/to/your/project\",\n#            integrationBranch: \"feature/my-plan\",  # the branch every task merges into (required)\n#            executorPath: \"<this-repo>\",           # absolute path of this clone: the workflow\n#                                                   # runs its bin/ scripts by exact path (required)\n#            openPr: true,                          # optional: push + open the PR at the end\n#            pr: { base: \"develop\", assignees: [\"me\"], labels: [\"story\"],\n#                  milestone: \"v1.2\", closes: 42 },  # optional PR fields (git-flow contract)\n#            mergeAuthorization: \"I authorize merging task-1 through task-N into <branch>\",\n#               # optional but recommended: your explicit authorization, so the merge\n#               # agent doesn't have to guess whether consent was already given (see the\n#               # permissions note in branching topology below)\n#            maxConcurrency: 3                      # optional, default unlimited — see below\n#            }\n```\n\n`maxConcurrency` caps how many tasks `cys:run` executes at once within a DAG layer. The\nClaude Code `Workflow` tool already queues excess `agent()` calls beyond its own\n`min(16, cores-2)` cap, so this is mainly useful to go *lower* than that — e.g. to avoid\nmany simultaneous local git worktrees on your own machine for a plan with a wide layer of\nindependent tasks. `/run-plan` and `/cys:flow` offer to set it for you when the parsed\nplan's inferred parallel width exceeds 6 — you don't need to compute this by hand.\n\n### The `/run-plan` slash command\n\nIf you'd rather not type out the natural-language request from the step-by-step guide\nevery time, this repo ships a Claude Code custom slash command that wraps it:\n`commands/run-plan.md`.\n\n#### Installing it\n\n1. Copy `commands/run-plan.md` from this repo to either:\n   - `~/.claude/commands/run-plan.md` — available in **every** project on your machine, or\n   - `<your-project>/.claude/commands/run-plan.md` — available only inside that one project.\n\n   Global (`~/.claude/commands/`) is the right choice for most people, since this tool is\n   meant to be invoked against other projects, not just the one it happens to live in.\n\n2. Open the copied file and replace the `REPO = ...` placeholder near the top with the\n   absolute path where you cloned **this** repo (`parallel-plan-executor`), e.g.\n   `REPO = /home/you/parallel-plan-executor`. This is the one thing you must edit — the\n   command has no other way to find the workflow script.\n\n3. That's it — no restart needed. Claude Code picks up commands under `.claude/commands/`\n   the next time you use them.\n\n#### Using it\n\n```\n/run-plan /path/to/your-plan.md /path/to/your/project feature/my-plan\n```\n\nAll three arguments are optional to type up front — the command will ask you for\nanything you leave out, plus whatever [manual invocation](#manual-invocation-reference)\nabove lists as optional (`openPr`, `pr` fields, your merge authorization). It never\ninvents your authorization text on your behalf; it always asks you to name the branches\nyourself.\n\n### Handoff phase\n\nWhen at least one task merged, a final **handoff agent** prepares the git-flow closing\nfor you — without executing it. It writes `.cys/handoff.md` in the target\nrepo with: a suggested Conventional-Commit PR title, a full PR body (Summary / Type of\nchange / Main changes / Version / Checklist), the proposed SemVer bump derived from the\nrun's commits (git-flow rules, `0.x` included), the final review verdict, and a post-run\ncleanup checklist.\n\nWith **`openPr: true`** (explicit consent given at launch) it additionally pushes the\nintegration branch and **creates** the pull request via `gh` against `pr.base` (default\n`develop`), applying the optional `pr` fields — assignees, labels, milestone, and\n`Closes #<closes>` in the body. **It never merges the PR**: that gate is human, always.\n\n### Recommended branching topology\n\nPoint `integrationBranch` at an **ephemeral feature branch cut from `develop`** — never\nat `develop`/`main` directly:\n\n```\nmain (release)                   ← never touched by agents\n  └── develop (integration)     ← never touched by agents\n        └── feature/<plan>      ← integrationBranch: task branches merge here ★\n              ├── task-1        ← one isolated worktree per implementer\n              └── task-N\n```\n\nWhy: mainline stays protected by construction (agent-written code never lands on a\nshared branch without human review), a failed run costs one `git branch -D`, and the\nhuman gate sits exactly where it belongs — the single `feature/<plan> → develop` PR you\nopen via `git-flow` after reviewing the finished branch.\n\n**Permissions note (read this if a merge gets blocked)**: under Claude Code's auto\nmode, an automatic classifier judges each agent action on its own, and agent-performed\n`git merge` is exactly the pattern it watches for. Passing your authorization text via\n`args.mergeAuthorization` helps the *merge agent itself* not self-block out of caution\n(finding F8 in `docs/pilots/2026-07-15-pilot-stats-bitacora.md`) — but it does **not**\nbind the classifier: in a later real run the classifier explicitly rejected that relayed\ntext as \"self-asserted, unverifiable\" consent and blocked the merge anyway. The\ndeterministic fix is the [one-time permissions setup](#one-time-permissions-setup-merges)\nabove: an `ask` (or `allow`) rule for `git merge` in the target project's\n`.claude/settings.json`, added by you. Rules take precedence over the mode — with the\nrule in place you get a plain yes/no dialog (or silent allow) instead of a classifier\njudgment call.\n\n## Building from source\n\nOnly needed if you're **contributing to this repo**, or want to run the raw\n`Workflow` script without going through the plugin commands. If you just want\nto *use* cys, [Quick Start](#quick-start) is enough — installing the plugin\nalready gives you a ready-to-run, pre-built copy.\n\n### Requirements\n\n- **[Claude Code](https://claude.com/claude-code)**, with access to the `Workflow` tool.\n  This is **not optional or swappable for another AI assistant**: the script in\n  `workflows/parallel-plan-executor.js` is written against that tool's primitives\n  (`agent()`, `pipeline()`, `parallel()`, etc.) — it isn't an open standard another\n  assistant (ChatGPT, Gemini, etc.) can interpret. What *is* agnostic is the **target\n  project** being automated: it can be Go, Node, Java, or whatever stack the plan\n  describes.\n- **The cys plugin** (see [Installing the cys plugin](#installing-the-cys-plugin)) for\n  authoring plans with `cys:plan`. The engine is fully self-contained: the workflow ships\n  its own `task-brief`/`review-package` scripts in `bin/` and records runs under `.cys/`.\n  Any plan following the `### Task N:` + `Consumes`/`Produces` format works, whatever\n  tool wrote it.\n- **Node.js >= 20** (for `bin/parse-plan.js` and the test suite — no runtime\n  dependencies, just standard Node).\n- Git, and a clean working tree in the project you're automating.\n- `gh` (GitHub CLI) installed and authenticated, **only if** you'll use `openPr: true`\n  (so the workflow can create the final PR).\n\n### Cloning and building\n\n```bash\n# 1. Clone this repo (where the workflow lives) onto your machine.\n#    WHERE: anywhere you like — your home folder, a tools directory, etc.\n#    It does NOT need to be inside .claude/, and it does NOT need to live next to\n#    the projects you'll automate; every path you pass it later is absolute.\ngit clone <this-repo-url> parallel-plan-executor\ncd parallel-plan-executor\n\n# 2. Check your Node version (must be >= 20)\nnode --version\n\n# 3. Install (no runtime dependencies; this just wires up the npm scripts)\nnpm install\n\n# 4. Run the test suite to confirm everything works in your environment\nnpm test\n\n# 5. Build the workflow artifact (regenerates workflows/parallel-plan-executor.js\n#    from the template — also re-run this after any change under src/)\nnpm run build\n```\n\nThat's it — the workflow is invoked **from a Claude Code session**, no need to publish\nit to npm or install it globally. See [Using cys](#using-cys) above. Before your first\nreal run, also do the [one-time permissions setup](#one-time-permissions-setup-merges)\nso task merges don't get blocked mid-run.\n\n## How it works\n\n1. `bin/parse-plan.js` reads a plan file and computes its task list + dependency graph\n   (pure Node, fully unit tested — see `tests/`).\n2. `workflows/parallel-plan-executor.js` (built from `workflows-src/parallel-plan-executor.template.js`\n   via `npm run build`) takes that graph and runs each task in its own git worktree via\n   `agent()`, starting a task the moment its specific dependencies finish rather than\n   waiting for a whole batch.\n3. Each task gets an adversarial review agent instead of a human checkpoint per task,\n   since a `Workflow` can't pause mid-run to ask you anything.\n4. Merges happen one at a time, serialized, respecting the dependency order.\n5. You get a single report at the end, and — if at least one task merged — a **Handoff**\n   agent prepares the git-flow closing for you (see [Handoff phase](#handoff-phase)).\n\n## Safety checks & known limitations\n\n### Safety checks (v0.2)\n\n- **Startup validation**: the workflow validates `args` before launching any agent —\n  a cyclic graph or an id present in `graph` but missing from `tasks` fails fast with a\n  clear error instead of deadlocking `runDag` silently.\n- **Same-file chaining**: tasks touching the same file are serialized as a chain (each\n  depends on the *last* task to touch it), so they never run in parallel against each\n  other.\n- **Duplicate-producer warnings**: two tasks declaring the same `Produces` symbol is\n  surfaced as a warning (first producer still wins); it does not abort the run.\n- **Skip reasons point at the root cause**: a task skipped through a cascade reports the\n  task that originally failed, not the intermediate skipped link.\n\n### Known limitations (v1)\n\n- Only backtick-quoted symbols count in `Consumes`/`Produces` (e.g.\n  `` - Produces: the `createWidget()` factory `` produces `createWidget`). Bare prose is\n  ignored on purpose: extracting every identifier turned words like \"the\" or \"None\" into\n  symbols and created spurious dependencies — even false cycles — between unrelated tasks.\n  `Consumes: None` is therefore simply an empty list.\n- The `Consumes`/`Produces` parser reads one line at a time — a value that wraps onto a\n  second line in the plan's prose won't be captured. A missed dependency does **not**\n  silently misorder tasks: the task starts without its real dependency in place, so it\n  either fails loudly (or self-reports `BLOCKED`) and its transitive dependents are\n  skipped, all surfaced in the final report. A retry-later mechanism (re-attempt once more\n  of the DAG has closed) was evaluated and deferred — see design spec §7 — so today the\n  only mitigation is keeping `Consumes`/`Produces` on one line per entry.\n- No speculative re-execution of an abnormally slow task (evaluated and deferred, see\n  design spec §7) — right-sizing tasks in the plan itself is the current mitigation.\n- `task-<id>` branches of failed or BLOCKED tasks survive the run on purpose: they\n  preserve whatever partial state exists for diagnosis. Clean them up afterwards with\n  `git branch -D task-<id>` once you no longer need them.\n\n## Reporting bugs & contributing\n\nOpen an issue at\n[github.com/bacsystem/parallel-plan-executor/issues](https://github.com/bacsystem/parallel-plan-executor/issues)\n(the bug report template will guide you). The single most useful thing\nyou can attach is something cys already generated for you — no need to\nwrite a fresh repro from scratch:\n\n- `.cys/pending.md`, if the run's final review or a `cys:check` call\n  already logged a finding about this.\n- `.cys/task-<id>-report.md`, for the specific task that misbehaved.\n- `review-*.diff`, if a review flagged something.\n- The exact stderr/stdout of a failing command (e.g. `node bin/parse-plan.js`).\n\nWant to contribute code or docs? See `CONTRIBUTING.md` for this repo's\nevidence-driven discipline (every behavior change needs a test tracing to a real\nfinding, plus a comment explaining why) and the TDD/build workflow.\n",
  "bytes": 31713,
  "sha": "c9fb1b2aa2cdde1b7f462bd9648b67f934a004f6d357bbd8ccf7c76b2a586f15",
  "repo_slug": "bacsystem/parallel-plan-executor",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_bacsystem_parallel_plan_executor_e2ecb531/readme"
}