{"id":50630651,"url":"https://github.com/aryeko/agentic-workflow-kit","last_synced_at":"2026-06-13T13:02:06.307Z","repository":{"id":362294966,"uuid":"1258269431","full_name":"aryeko/agentic-workflow-kit","owner":"aryeko","description":"Tracker-driven, spec-first delivery for any repo — a Claude Code \u0026 Codex plugin plus an optional autonomous orchestrator. PR/merge policy is declarative config.","archived":false,"fork":false,"pushed_at":"2026-06-11T01:16:25.000Z","size":675,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-11T01:21:12.431Z","etag":null,"topics":["agentic-workflows","ai-agents","automation","claude-code","claude-code-plugin","cli","codex","developer-tools","llm-orchestration","mcp","model-context-protocol","openai-codex","spec-driven-development","tracker-driven","typescript","workflow-automation"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aryeko.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-03T12:27:35.000Z","updated_at":"2026-06-11T01:15:44.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/aryeko/agentic-workflow-kit","commit_stats":null,"previous_names":["aryeko/agentic-workflow-kit"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/aryeko/agentic-workflow-kit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aryeko%2Fagentic-workflow-kit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aryeko%2Fagentic-workflow-kit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aryeko%2Fagentic-workflow-kit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aryeko%2Fagentic-workflow-kit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aryeko","download_url":"https://codeload.github.com/aryeko/agentic-workflow-kit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aryeko%2Fagentic-workflow-kit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34285191,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-13T02:00:06.617Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-workflows","ai-agents","automation","claude-code","claude-code-plugin","cli","codex","developer-tools","llm-orchestration","mcp","model-context-protocol","openai-codex","spec-driven-development","tracker-driven","typescript","workflow-automation"],"created_at":"2026-06-06T21:00:28.035Z","updated_at":"2026-06-13T13:02:06.267Z","avatar_url":"https://github.com/aryeko.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/branding/rail-contract/hero-1280x400.png\" alt=\"agentic-workflow-kit — one tracker, two drivers\" width=\"100%\" /\u003e\n\u003c/p\u003e\n\n[![CI](https://github.com/aryeko/agentic-workflow-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/aryeko/agentic-workflow-kit/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![Node \u003e=24](https://img.shields.io/badge/node-%3E%3D24-brightgreen)](https://nodejs.org)\n\nA generic, OSS Claude Code + Codex plugin, with a package-backed MCP runtime and optional standalone CLI,\nthat turns any repo into a\n**tracker-driven, spec-first delivery pipeline** — and makes the per-repo differences (most\nnotably PR/merge gating) **declarative config** rather than forked skills.\n\nThe core idea: one **markdown tracker** (a status matrix + dependency graph) plus one\n**`.workflow/config.yaml`** form a single contract that two interchangeable drivers read — an\n**interactive** \"one story at a time\" skill and an **autonomous** multi-session orchestrator.\n\n## Use it when\n\n- You want product, technical, and delivery planning to produce durable repo artifacts instead of\n  chat-only plans.\n- You want implementation state to live in a reviewable markdown tracker, not in a transient agent\n  transcript.\n- You want Claude Code and Codex to follow the same workflow contract.\n- You want PR, CI, review, and merge behavior to be per-repo config rather than copied prompt text.\n\n## Quick Start\n\nInstall the plugin, then initialize a repo:\n\n```text\n/agentic-workflow-kit:workflow-init\n/agentic-workflow-kit:define-product\n/agentic-workflow-kit:plan-delivery-track\n/agentic-workflow-kit:implement-next\n```\n\nFor autonomous dispatch, use `workflow-autopilot` from a plugin session. For terminal and CI use,\ninstall the package runtime:\n\n```bash\npnpm add -D @agentic-workflow-kit/orchestrator\npnpm exec agentic-workflow-kit list-eligible --cwd .\n```\n\n## Architecture\n\n```mermaid\nflowchart LR\n  subgraph Author[\"Author (skills)\"]\n    PP[define-product] --\u003e PA[design-technical-solution\u003cbr/\u003ewhen needed]\n    PP --\u003e PT[plan-delivery-track]\n    PA --\u003e PT\n  end\n  WI[workflow-init] --\u003e CFG\n  PT --\u003e TRK\n  subgraph Contract[\"Shared contract (the spine)\"]\n    CFG[\".workflow/config.yaml\"]\n    TRK[\"markdown trackers\"]\n  end\n  CFG --\u003e IN[\"implement-next\u003cbr/\u003e(interactive)\"]\n  TRK --\u003e IN\n  CFG --\u003e OR[\"package MCP runtime\u003cbr/\u003eor CLI\u003cbr/\u003e(autonomous)\"]\n  TRK --\u003e OR\n  OR --\u003e CODEX[\"Codex MCP child sessions\"]\n  CODEX -. update .-\u003e TRK\n```\n\n`workflow-init` scaffolds the config; `define-product`, `design-technical-solution` when needed, and\n`plan-delivery-track` produce the PRD, technical solution, and tracker.\nThat config + tracker is the single contract both drivers consume. Completion authority is always\nthe tracker row — never a child session's prose. Full detail and more diagrams in\n[docs/architecture.md](docs/architecture.md).\n\n## How it works\n\n```mermaid\nflowchart LR\n  A[\"/workflow-init\u003cbr/\u003econfig + scaffolding\u003cbr/\u003e\u003ci\u003e(once per repo)\u003c/i\u003e\"] --\u003e B[\"/define-product\u003cbr/\u003eauthor PRD\"]\n  B --\u003e C{\"technical\u003cbr/\u003esolution needed?\"}\n  C --\u003e|yes| D[\"/design-technical-solution\u003cbr/\u003ehigh-level technical how\"]\n  C --\u003e|no| E[\"/plan-delivery-track\u003cbr/\u003etracker + briefs\"]\n  D --\u003e E\n  E --\u003e F{Drive how?}\n  F --\u003e|interactive| G[\"/implement-next\u003cbr/\u003eone story end-to-end\"]\n  F --\u003e|autonomous| H[\"orchestrator run-eligible\u003cbr/\u003efan out child sessions\"]\n  G --\u003e I[\"ship per pr: policy\u003cbr/\u003e(create / CI / review / merge)\"]\n  H --\u003e I\n  I --\u003e J{More eligible\u003cbr/\u003estories?}\n  J --\u003e|yes| F\n  J --\u003e|no| K[\"track complete\"]\n```\n\n1. **Set up once** — `/workflow-init` detects your package manager, CI, default branch, and branch\n   protection, picks a PR/merge preset, writes `.workflow/config.yaml`, and scaffolds a tracks\n   index plus an example tracker.\n2. **Plan the product** — `/define-product` runs a guided interview into a multi-file PRD.\n3. **Design the technical solution when needed** — `/design-technical-solution` turns complex PRDs into a\n   technical solution document before story slicing.\n4. **Decompose into a tracker** — `/plan-delivery-track` turns the PRD, and technical solution when present, into a\n   tracker plus story briefs.\n5. **Implement** — `/implement-next` takes one eligible story end-to-end (isolate → spec review →\n   plan → implement → review → verify → ship), or `workflow-autopilot` uses the plugin-provided MCP runtime\n   to fan eligible stories out to Codex child sessions autonomously. The CLI provides the same\n   runtime for local development, CI, and troubleshooting.\n6. **Ship** — under the declarative `pr:` policy (open a PR, wait on CI/review, auto-merge — or\n   not), then repeat until the tracker is drained.\n\n## PR/merge presets\n\nThe one block that genuinely differs between repos is `pr:`. Pick a preset and go:\n\n| Preset | Waits on CI | Waits on review | Auto-merge | Mirrors |\n| --- | --- | --- | --- | --- |\n| `push-and-merge` | no | no | yes (squash) | a repo that ships fast |\n| `gated-automerge` | yes | bot (e.g. codex) | yes (squash) | a repo with CI + bot review |\n| `push-only` | no | no | no (open PR, stop) | a repo with human review gates |\n\nSwitch behavior by editing the `pr:` block in `.workflow/config.yaml`. See\n[references/config-schema.md](references/config-schema.md).\n\nFor the `gated-automerge` preset, `pr.review.wait: bot` with `pr.review.bot: codex` waits on\nCodex's GitHub reaction/comment signal: eyes means started or pending, thumbs-up means clear/no\nfindings, and Codex PR review comments or PR comments are findings to triage when\n`triageComments: true`. It does not require Codex to submit a native GitHub approval.\n\n## Documentation\n\n- [docs/README.md](docs/README.md) — documentation hub (using vs developing)\n- [docs/architecture.md](docs/architecture.md) — architecture, flows, and runtime diagrams\n- [docs/getting-started.md](docs/getting-started.md) — a guided walkthrough using the Linkly example\n- [references/config-schema.md](references/config-schema.md) — the `.workflow/config.yaml` reference\n- [references/tracker-contract.md](references/tracker-contract.md) — the tracker format + status vocabulary\n- [references/prd-contract.md](references/prd-contract.md) — the PRD format\n- [references/technical-solution-contract.md](references/technical-solution-contract.md) — the technical solution gate format\n- [references/story-brief-contract.md](references/story-brief-contract.md) — the lightweight story brief format\n- [references/detailed-story-spec-contract.md](references/detailed-story-spec-contract.md) — the pre-code detailed story spec format\n- [examples/](examples/) — a worked PRD and tracker (Linkly)\n- [CONTRIBUTING.md](CONTRIBUTING.md) — how to develop and contribute\n- [docs/brand.md](docs/brand.md) — the visual identity (logo, color, type, social/SEO kit)\n\n## Install\n\n### Claude Code plugin\n\n```text\n/plugin marketplace add aryeko/agentic-workflow-kit\n/plugin install agentic-workflow-kit@agentic-workflow-kit\n```\n\n### Codex plugin\n\nAdd the marketplace from the CLI ([Codex docs](https://developers.openai.com/codex/plugins/build#add-a-marketplace-from-the-cli)),\nthen install from the Codex plugin directory:\n\n```bash\ncodex plugin marketplace add aryeko/agentic-workflow-kit\n```\n\nRestart Codex, then open the plugin directory, select the `agentic-workflow-kit` marketplace, and install\nthe `agentic-workflow-kit` plugin (CLI equivalent: `codex plugin add agentic-workflow-kit@agentic-workflow-kit`).\n\n### Optional standalone CLI\n\n```bash\npnpm add -D @agentic-workflow-kit/orchestrator\npnpm exec agentic-workflow-kit --help\n```\n\nThe package also publishes the MCP executable used by plugin installs:\n\n```bash\nnpx -y --package @agentic-workflow-kit/orchestrator@\u003cexact-version\u003e agentic-workflow-kit-mcp\n```\n\nSee the [package README](packages/orchestrator/README.md) for CLI and MCP runtime details.\n\n## Local development\n\n```bash\npnpm install\npnpm check\npnpm agentic-workflow-kit -- --help\n```\n\nOptional local Codex plugin smoke requires the Codex CLI. It is intentionally outside `pnpm check`\nso the default development gate works on machines that only have the package toolchain installed.\n\n## Local plugin testing\n\nThe repository includes local-only plugin metadata for development testing:\n\n- Claude Code: load this repo with `claude --plugin-dir ./`, then invoke namespaced skills such as\n  `/agentic-workflow-kit:workflow-init`; the root `.mcp.json` wires the package MCP runtime.\n- Codex: `.agents/plugins/marketplace.json` is the marketplace manifest — the same one a public\n  `codex plugin marketplace add aryeko/agentic-workflow-kit` reads. Locally you add it from the repo\n  directory; it points at the materialized fixture at `./plugins/agentic-workflow-kit`, including\n  the fixture-specific MCP manifest. The Codex plugin manifest declares\n  `mcpServers: \"./.codex-plugin/.mcp.json\"`; that file uses Codex's `mcpServers` shape so Codex can\n  launch the package MCP server without reusing Claude Code's root `.mcp.json`. Both plugin surfaces\n  run `npx -y --package @agentic-workflow-kit/orchestrator@\u003cexact-version\u003e agentic-workflow-kit-mcp`.\n  Codex entries omit `cwd`; workflow MCP tools operate on the target repo when Codex provides that\n  cwd, and callers can still pass the tool `cwd` argument explicitly when needed. If `cwd` is omitted\n  and no workflow config is visible, the tools return an actionable error.\n\n```bash\ntmp_home=\"$(mktemp -d)\"\nCODEX_HOME=\"$tmp_home\" codex plugin marketplace add .\nCODEX_HOME=\"$tmp_home\" codex plugin list\nCODEX_HOME=\"$tmp_home\" codex plugin add agentic-workflow-kit@agentic-workflow-kit\nCODEX_HOME=\"$tmp_home\" codex plugin list\n```\n\nThe same Codex install and prompt-visibility check is available as:\n\n```bash\npnpm smoke:codex-plugin\n```\n\nThat smoke installs through a temporary `CODEX_HOME`, verifies prompt visibility, starts the\ninstalled package MCP command from a non-plugin consumer cwd, and reaches `tools/list`. If Codex\nreports `connection closed: initialize response`, do not assume the package MCP server JavaScript is\ninvalid. First check the installed MCP config, package specifier, npm cache/network access, and\ninstalled plugin cache version:\n\n```bash\ncodex plugin list\nfind \"$CODEX_HOME/plugins/cache/agentic-workflow-kit/agentic-workflow-kit\" -maxdepth 1 -type d\ncat \"$CODEX_HOME/plugins/cache/agentic-workflow-kit/agentic-workflow-kit/\u003cversion\u003e/.codex-plugin/.mcp.json\"\n```\n\nThe marketplace source version, installed cache version, and already-running Codex session can\ndrift. After changing plugin manifests or MCP wiring, reinstall the plugin into the relevant\n`CODEX_HOME` and relaunch Codex so the active session reloads the installed cache.\n\nKeep manual plugin smokes pending until they are run in the relevant tool environment.\n\n## Layout\n\n- `skills/` — the plugin's instructions and slash-command entry points.\n- `references/` — the config schema (human + machine), tracker, PRD, technical solution contracts, and templates.\n- `presets/` — the three starter configs.\n- `examples/` — a worked PRD and tracker.\n- `packages/orchestrator/` — the TypeScript runtime source: the config schema, loader, presets, MCP server adapter, autonomous multi-session orchestrator, standalone CLI, and package MCP executable.\n- `docs/` — architecture, the docs hub, and the getting-started guide.\n\n## Project status\n\nagentic-workflow-kit plugin and package manifests are versioned together: the six skills\n(`workflow-init`, `define-product`, `design-technical-solution`, `plan-delivery-track`,\n`implement-next`, `workflow-autopilot`), the package-backed MCP runtime, the contracts, the three\npresets, the worked examples, and the optional standalone `@agentic-workflow-kit/orchestrator` CLI\npackage are implemented and covered by the test suite (`pnpm check`).\n\nIt is an early **0.x** release — the install paths above are live. Feedback and issues are welcome as the\nagent-driven skills get broader real-world mileage.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faryeko%2Fagentic-workflow-kit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faryeko%2Fagentic-workflow-kit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faryeko%2Fagentic-workflow-kit/lists"}