{"_id":"@aramirez087/epic-toolkit","_rev":"4-2bb9fdf5eaf9a37b2780fa2f0e938581","name":"@aramirez087/epic-toolkit","dist-tags":{"latest":"1.15.36"},"versions":{"1.15.31":{"name":"@aramirez087/epic-toolkit","version":"1.15.31","_id":"@aramirez087/epic-toolkit@1.15.31","maintainers":[{"name":"aramirez087","email":"alexramirez.cr@gmail.com"}],"dist":{"shasum":"634d63b3f22767fcc410f95d696a38a165a59a2e","tarball":"https://registry.npmjs.org/@aramirez087/epic-toolkit/-/epic-toolkit-1.15.31.tgz","fileCount":6,"integrity":"sha512-Y+4Aezv9VvkSJ0dT+tlJItsHS84DhLsJ7bHlatCH+ggacdXlnDnUugqONNfTeVVdYKxmyY/wsLtx0WMpC1jojQ==","signatures":[{"sig":"MEQCIAleNLVstNmjTXhQQ36myJGOuIMK/T/bTVh814esVYmLAiB+LrY9dKEzXtdVs9FfTiwQsyeAU5oos6HccSkLBCk1Tw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":31619},"gitHead":"08fff7d2f1ce5de7f2a60065c8fdec92aeba44cd","_npmUser":{"name":"aramirez087","email":"alexramirez.cr@gmail.com"},"_npmVersion":"11.12.1","directories":{},"_nodeVersion":"24.15.0","dependencies":{"@opencode-ai/plugin":"1.15.31"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/epic-toolkit_1.15.31_1778505133591_0.11843707904266587","host":"s3://npm-registry-packages-npm-production"}},"1.15.34":{"name":"@aramirez087/epic-toolkit","version":"1.15.34","_id":"@aramirez087/epic-toolkit@1.15.34","maintainers":[{"name":"aramirez087","email":"alexramirez.cr@gmail.com"}],"dist":{"shasum":"29a9fb708a57f40e2a58a3e7cf82213b086de99c","tarball":"https://registry.npmjs.org/@aramirez087/epic-toolkit/-/epic-toolkit-1.15.34.tgz","fileCount":37,"integrity":"sha512-q1UDVL7qV6RYQm2I2J3QCiMIsYN9wLY0j6mupL23vCLyQx52gNanJrFan9wMvJslxeSD/uU+d908fGjo4hwuxA==","signatures":[{"sig":"MEYCIQCGp7TeYN2kyuOAxNFaugJnxr673xdT48m7SgJTPjjPkQIhAMHNvnWK84as6x8vYLhgXzyOff8vvmMCTZ+KklYxKRhJ","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":519219},"gitHead":"c039c716ff6e24dba1b8e8518609041e393fb828","_npmUser":{"name":"aramirez087","email":"alexramirez.cr@gmail.com"},"_npmVersion":"11.12.1","description":"Run multi-session epics as a **directed acyclic graph**, with **parallel siblings executing in their own git worktrees** and merging back into a coordinator trunk branch wave by wave. Works with both **Claude Code** and **OpenCode**.","directories":{},"_nodeVersion":"24.15.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/epic-toolkit_1.15.34_1780842101079_0.8562260578392129","host":"s3://npm-registry-packages-npm-production"}},"1.15.35":{"name":"@aramirez087/epic-toolkit","version":"1.15.35","_id":"@aramirez087/epic-toolkit@1.15.35","maintainers":[{"name":"aramirez087","email":"alexramirez.cr@gmail.com"}],"dist":{"shasum":"d4d358285bad60423990f1c39f8a8db7956d448d","tarball":"https://registry.npmjs.org/@aramirez087/epic-toolkit/-/epic-toolkit-1.15.35.tgz","fileCount":37,"integrity":"sha512-wTpL+dkf8mGxlgFSZGJnosNVp00ziNzGCanSk9PhTtt7ndo89blPspzX3YuqVSPVbythlFPOni6ufgItqFNQ0g==","signatures":[{"sig":"MEQCIDyQ29QkkhUxCHQQILS9KMFIfPVNWPIBqLbP7aPzDggSAiADoFJpBjxupFNEBiNzSifblVRSlyI6WagWupY40sKl4w==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":519808},"gitHead":"fc36c5619ae0a17ed8c9645541c57d5035842045","_npmUser":{"name":"aramirez087","email":"alexramirez.cr@gmail.com"},"_npmVersion":"11.12.1","description":"Run multi-session epics as a **directed acyclic graph**, with **parallel siblings executing in their own git worktrees** and merging back into a coordinator trunk branch wave by wave. Works with both **Claude Code** and **OpenCode**.","directories":{},"_nodeVersion":"24.15.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/epic-toolkit_1.15.35_1781023432652_0.781303658239155","host":"s3://npm-registry-packages-npm-production"}},"1.15.36":{"name":"@aramirez087/epic-toolkit","version":"1.15.36","gitHead":"97c058d0af2ac74020164a47243f54d5c072ac50","_id":"@aramirez087/epic-toolkit@1.15.36","description":"Run multi-session epics as a **directed acyclic graph**, with **parallel siblings executing in their own git worktrees** and merging back into a coordinator trunk branch wave by wave. Works with both **Claude Code** and **OpenCode**.","_nodeVersion":"24.15.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-d4xRz9xTZQlJF7DnLrtNpA48SwVJQNdM9WLSJURgz1Fe7t9tTzMnGgJh64ItpeL+7MCr3uOmmYPQLOchz14ObA==","shasum":"2ffe1a565e1e9f651c55c4e388d2324362163933","tarball":"https://registry.npmjs.org/@aramirez087/epic-toolkit/-/epic-toolkit-1.15.36.tgz","fileCount":37,"unpackedSize":519872,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQC8upLEw84u+BP6Cl71f/PKioTmVwKJx2WjBla48xMhcAIhAJiblyZZkFV1aZd1X/PV8zwJP3ppSyXIE7Py67HbVtRg"}]},"_npmUser":{"name":"aramirez087","email":"alexramirez.cr@gmail.com"},"directories":{},"maintainers":[{"name":"aramirez087","email":"alexramirez.cr@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/epic-toolkit_1.15.36_1781023792815_0.01747291101316084"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-11T13:12:13.454Z","modified":"2026-06-09T16:49:53.060Z","1.15.31":"2026-05-11T13:12:13.726Z","1.15.34":"2026-06-07T14:21:41.233Z","1.15.35":"2026-06-09T16:43:52.827Z","1.15.36":"2026-06-09T16:49:52.945Z"},"description":"Run multi-session epics as a **directed acyclic graph**, with **parallel siblings executing in their own git worktrees** and merging back into a coordinator trunk branch wave by wave. Works with both **Claude Code** and **OpenCode**.","maintainers":[{"name":"aramirez087","email":"alexramirez.cr@gmail.com"}],"readme":"# epic-toolkit\n\nRun multi-session epics as a **directed acyclic graph**, with **parallel siblings\nexecuting in their own git worktrees** and merging back into a coordinator trunk\nbranch wave by wave. Works with both **Claude Code** and **OpenCode**.\n\n![demo](https://raw.githubusercontent.com/aramirez087/epic-toolkit/main/docs/demo.gif)\n\nAdds three slash commands:\n\n- Claude Code: `/epic-toolkit:epic.generate <problem statement>` — turns a problem statement into a\n  sequence of session prompt files with DAG metadata. For large multi-subsystem\n  initiatives it splits the work into multiple epic directories and emits a\n  matching sprint config.\n- Claude Code: `/epic-toolkit:epic <name>` — runs the generated epic, fanning out parallel waves and\n  auto-creating a PR when done.\n- Claude Code: `/epic-toolkit:sprint <sprint.json | epic-dir...>` — runs N epics\n  back-to-back on a shared trunk branch and opens a single PR for the whole\n  sprint (multi-epic orchestrator).\n\nOpenCode exposes the same commands without the Claude plugin namespace:\n`/epic.generate`, `/epic`, and `/sprint`.\n\n## Install\n\n**Claude Code:**\n\n```\n/plugin marketplace add aramirez087/epic-toolkit\n/plugin install epic-toolkit@epic-toolkit\n```\n\nThen run the namespaced Claude Code commands:\n\n```\n/epic-toolkit:epic.generate <problem statement>\n/epic-toolkit:epic <name>\n/epic-toolkit:sprint <sprint.json>          # multi-epic, one PR\n```\n\nFor terminal/scripted setup, the equivalent commands are:\n\n```bash\nclaude plugin marketplace add aramirez087/epic-toolkit\nclaude plugin install epic-toolkit@epic-toolkit\n```\n\n**OpenCode:**\n\nThe `.opencode/commands/` directory is auto-detected. Clone the repo or symlink\n`.opencode/commands/` into your project and the `/epic`, `/epic.generate`, and\n`/sprint` commands will be available.\n\n## Release / update policy\n\nThis plugin uses an explicit version in `.claude-plugin/plugin.json`. Bump that\nversion for every user-facing release; Claude Code uses it to decide whether\ninstalled users should receive updates. The marketplace entry intentionally does\nnot duplicate the version, so the plugin manifest remains the single source of\ntruth.\n\n## Dual-tool support\n\nThe orchestrator auto-detects which CLI is running (`claude` vs `opencode`) via\nenvironment variables and PATH lookup. You can force a specific CLI with the\n`--cli` flag:\n\n```bash\nbash scripts/run-sessions.sh docs/claude-sessions/my-epic --cli opencode\nbash scripts/run-sessions.sh docs/claude-sessions/my-epic --cli claude\n```\n\nProgress display adapts to the CLI:\n- **Claude Code**: streams `--output-format stream-json` through\n  `epic-progress.py` for real-time step/tool/target tracking.\n- **OpenCode**: streams `--format json` through `epic-progress.py` for the\n  same real-time tracking. Both formats are auto-detected.\n\n## What it does\n\n1. **`/epic-toolkit:epic.generate`** writes session prompts under\n   `docs/claude-sessions/<epic-name>/`. Each session 01+ gets YAML frontmatter\n   declaring its DAG edges (`depends_on`, `touches`, `parallel_safe`).\n2. **`/epic-toolkit:epic`** invokes the runner. It:\n   - Validates the DAG (no cycles, all deps exist).\n   - Computes Kahn-style waves (independent sessions in the same wave).\n   - Creates a trunk worktree on `epic/<name>` and per-session worktrees on\n     `epic/<name>/sNN-<slug>` for each sibling, branched off the trunk's HEAD.\n   - Runs up to `--max-parallel` (default 4) sessions in a wave concurrently\n     with a fresh CLI process each (PLAN pass → EXECUTE pass).\n   - Iteratively `--no-ff` merges successful siblings into trunk between waves.\n   - Auto-commits, auto-creates a GitHub PR via `gh`, cleans up worktrees.\n3. **`/epic-toolkit:sprint`** runs N epics back-to-back on a shared trunk\n   branch and opens a single PR for the whole sprint. Each epic is a normal\n   `/epic-toolkit:epic` run; the wrapper enforces sequential execution,\n   forwards `--no-pr` to every epic except the final one, and emits a single\n   sprint-level summary.\n\n## Layout produced by `/epic-toolkit:epic.generate`\n\n```\ndocs/claude-sessions/<epic-name>/\n  session-00-operator-rules.md     # prepended to every session\n  session-01-charter.md            # solo wave (parallel_safe: false)\n  session-02-auth.md               # wave 2 sibling (depends_on: [01])\n  session-03-email.md               # wave 2 sibling (depends_on: [01])\n  session-04-billing.md            # wave 2 sibling (depends_on: [01])\n  session-05-admin-ui.md           # wave 3 (depends_on: [02, 04])\n  session-06-ci-gate.md            # final solo wave (depends_on: all)\n```\n\n`epic-dag.py --show` renders this as:\n\n```\n  ║ Wave 1: [01 charter ]\n  ╠ Wave 2: [02 auth   ]  [03 email   ]  [04 billing ]\n  ║ Wave 3: [05 admin-ui]\n  ║ Wave 4: [06 ci-gate]\n```\n\n## Frontmatter fields\n\n```yaml\n---\nsession: 03\ntitle: \"Email worker\"\ndepends_on: [01]              # parents in the DAG\ntouches:                      # globs this session may modify\n  - src/email/**\nparallel_safe: true           # false forces a solo wave\nmodel: \"opus\"                 # override default model for this session\ncli: \"claude\"                 # override CLI auto-detection for this session\n---\n```\n\nSessions without frontmatter form an implicit linear chain (one per wave) —\nthe toolkit is fully back-compatible with pre-DAG epics.\n\n## Common flags\n\n| Flag | Default | Description |\n|---|---|---|\n| `--max-parallel N` | 4 | Concurrent sessions per wave |\n| `--strict` | off | Fail on `touches` overlap between siblings |\n| `--show-dag` | off | Print the wave layout and exit |\n| `--dry-run` | off | Preview without executing (non-destructive) |\n| `--start N` | 1 | Resume from session N |\n| `--sequential` | off | Force one session per wave (legacy linear) |\n| `--model M` | sonnet | Model name (passed to CLI; e.g. `opus`, `sonnet`, `haiku` for Claude) |\n| `--cli CMD` | auto | Force CLI: `opencode` or `claude` |\n| `--no-worktree` | off | Run trunk in CWD (forces sequential) |\n| `--timeout N` | 0 | Session timeout in minutes (0 = no timeout) |\n| `--retry N` | 0 | Retry failed sessions N times (0 = no retry) |\n\nSee [`docs/epic-guide.md`](docs/epic-guide.md) for the full reference.\n\n## Requirements\n\n- OpenCode (`opencode`) **or** Claude Code (`claude`) on `PATH` — auto-detected, or force with `--cli`\n- Python 3.8+ (stdlib only — no extra packages)\n- Bash 3.2+\n- `git` 2.20+\n- `gh` CLI (optional, for auto-PR creation)\n\n## Configuration File\n\nCreate `.epic-config.json` in your repository root to set default values:\n\n```json\n{\n  \"timeout\": 30,\n  \"retry\": 1,\n  \"model\": \"sonnet\",\n  \"cli\": \"opencode\",\n  \"maxParallel\": 6\n}\n```\n\nCLI flags override config file values. All keys are optional.\n\n## Files\n\n```\n.claude-plugin/\n  plugin.json              # Claude Code plugin manifest\n  marketplace.json         # makes the repo a self-installable marketplace\n.opencode/\n  commands/                # OpenCode slash commands\n    epic.md\n    epic.generate.md\n    sprint.md\ncommands/\n  epic.md                  # Claude Code /epic-toolkit:epic slash command\n  epic.generate.md         # Claude Code /epic-toolkit:epic.generate slash command\n  sprint.md                # Claude Code /epic-toolkit:sprint slash command (multi-epic)\nscripts/\n  run-sessions.sh          # wave orchestrator (dual-tool: claude or opencode)\n  run-sprint.sh            # multi-epic sprint orchestrator (one PR for N epics)\n  epic-dag.py              # DAG builder + wave scheduler\n  epic-progress.py         # stream-json progress display (claude and opencode)\n  epic-ui.py               # live terminal dashboard (used by run-sessions.sh)\ndocs/\n  epic-guide.md            # full user guide\n  epic-prompt-template.md\n```\n\n## License\n\nMIT.\n","readmeFilename":"README.md"}