Agentic Workflow Kit

[](https://github.com/aryeko/agentic-workflow-kit/actions/workflows/ci.yml) [](LICENSE) [](https://nodejs.org)

A generic, OSS Claude Code + Codex plugin, with a package-backed MCP runtime and optional standalone CLI, that turns any repo into a tracker-driven, spec-first delivery pipeline — and makes the per-repo differences (most notably PR/merge gating) declarative config rather than forked skills.

The core idea: one markdown tracker (a status matrix + dependency graph) plus one .workflow/config.yaml form a single contract that two interchangeable drivers read — an interactive "one story at a time" skill and an autonomous multi-session orchestrator.

Use it when

• You want product, technical, and delivery planning to produce durable repo artifacts instead of

chat-only plans.

• You want implementation state to live in a reviewable markdown tracker, not in a transient agent

transcript.

• You want Claude Code and Codex to follow the same workflow contract.
• You want PR, CI, review, and merge behavior to be per-repo config rather than copied prompt text.

Quick Start

Install the plugin, then initialize a repo:

/agentic-workflow-kit:workflow-init
/agentic-workflow-kit:define-product
/agentic-workflow-kit:plan-delivery-track
/agentic-workflow-kit:implement-next

For autonomous dispatch, use workflow-autopilot from a plugin session. For terminal and CI use, install the package runtime:

pnpm add -D @agentic-workflow-kit/orchestrator
pnpm exec agentic-workflow-kit list-eligible --cwd .

Architecture

flowchart LR
  subgraph Author["Author (skills)"]
    PP[define-product] --> PA[design-technical-solutionwhen needed]
    PP --> PT[plan-delivery-track]
    PA --> PT
  end
  WI[workflow-init] --> CFG
  PT --> TRK
  subgraph Contract["Shared contract (the spine)"]
    CFG[".workflow/config.yaml"]
    TRK["markdown trackers"]
  end
  CFG --> IN["implement-next(interactive)"]
  TRK --> IN
  CFG --> OR["package MCP runtimeor CLI(autonomous)"]
  TRK --> OR
  OR --> CODEX["Codex MCP child sessions"]
  CODEX -. update .-> TRK

workflow-init scaffolds the config; define-product, design-technical-solution when needed, and plan-delivery-track produce the PRD, technical solution, and tracker. That config + tracker is the single contract both drivers consume. Completion authority is always the tracker row — never a child session's prose. Full detail and more diagrams in [docs/architecture.md](docs/architecture.md).

How it works

flowchart LR
  A["/workflow-initconfig + scaffolding(once per repo)"] --> B["/define-productauthor PRD"]
  B --> C{"technicalsolution needed?"}
  C -->|yes| D["/design-technical-solutionhigh-level technical how"]
  C -->|no| E["/plan-delivery-tracktracker + briefs"]
  D --> E
  E --> F{Drive how?}
  F -->|interactive| G["/implement-nextone story end-to-end"]
  F -->|autonomous| H["orchestrator run-eligiblefan out child sessions"]
  G --> I["ship per pr: policy(create / CI / review / merge)"]
  H --> I
  I --> J{More eligiblestories?}
  J -->|yes| F
  J -->|no| K["track complete"]

1. Set up once — /workflow-init detects your package manager, CI, default branch, and branch

protection, picks a PR/merge preset, writes .workflow/config.yaml, and scaffolds a tracks index plus an example tracker.

1. Plan the product — /define-product runs a guided interview into a multi-file PRD.
2. Design the technical solution when needed — /design-technical-solution turns complex PRDs into a

technical solution document before story slicing.

1. Decompose into a tracker — /plan-delivery-track turns the PRD, and technical solution when present, into a

tracker plus story briefs.

1. Implement — /implement-next takes one eligible story end-to-end (isolate → spec review →

plan → implement → review → verify → ship), or workflow-autopilot uses the plugin-provided MCP runtime to fan eligible stories out to Codex child sessions autonomously. The CLI provides the same runtime for local development, CI, and troubleshooting.

1. Ship — under the declarative pr: policy (open a PR, wait on CI/review, auto-merge — or

not), then repeat until the tracker is drained.

PR/merge presets

The one block that genuinely differs between repos is pr:. Pick a preset and go:

| Preset | Waits on CI | Waits on review | Auto-merge | Mirrors | | --- | --- | --- | --- | --- | | push-and-merge | no | no | yes (squash) | a repo that ships fast | | gated-automerge | yes | bot (e.g. codex) | yes (squash) | a repo with CI + bot review | | push-only | no | no | no (open PR, stop) | a repo with human review gates |

Switch behavior by editing the pr: block in .workflow/config.yaml. See [references/config-schema.md](references/config-schema.md).

For the gated-automerge preset, pr.review.wait: bot with pr.review.bot: codex waits on Codex's GitHub reaction/comment signal: eyes means started or pending, thumbs-up means clear/no findings, and Codex PR review comments or PR comments are findings to triage when triageComments: true. It does not require Codex to submit a native GitHub approval.

Runtime policy and artifacts

.workflow/config.yaml also controls runtime execution details beyond PR policy:

• agents.profiles defines named launch profiles for story implementation, pre-PR review,

planning, analysis, recovery, and tracker migration. Profiles carry driver, model, reasoning, prompt template, structured-output contract, sandbox, approval policy, host settings, and budget policy.

• childSession.speed controls Codex child-session speed policy: derive preserves the user's

global Codex setting, fast requests Fast mode, and standard explicitly opts child sessions out of inherited Fast mode.

• agents.bindings maps logical task types to those profiles, so a repo can change runtime policy

without editing generated prompts.

• Budget outcomes are written to budgets.json; wall-time and tool-call dimensions can drive

warnings, stop-new-launches, checkpoint stops, or aborts, while unavailable telemetry is reported explicitly instead of as zero.

• Launch artifacts record the resolved profile, prompt template/hash, structured-output intent, and

any capability downgrade such as Codex MCP structured-output enforcement being recorded rather than host-enforced.

• Run artifacts live under .codex/agentic-workflow-kit/runs// and can be inspected,

reported, exported, or controlled through the product CLI/MCP facade. Report/export operations are explicit and do not copy host transcript contents by default.

• GitHub collaboration evidence is structured: PR number/URL, checks, Codex reaction/comment review

signal, findings triage, merge method/commit, and branch deletion are captured for analyzer and completion-gate decisions.

Documentation

• [docs/README.md](docs/README.md) — documentation hub (using vs developing)
• [docs/architecture.md](docs/architecture.md) — architecture, flows, and runtime diagrams
• [docs/getting-started.md](docs/getting-started.md) — a guided walkthrough using the Linkly example
• [references/config-schema.md](references/config-schema.md) — the .workflow/config.yaml reference
• [references/tracker-contract.md](references/tracker-contract.md) — the tracker format + status vocabulary
• [references/prd-contract.md](references/prd-contract.md) — the PRD format
• [references/technical-solution-contract.md](references/technical-solution-contract.md) — the technical solution gate format
• [references/story-brief-contract.md](references/story-brief-contract.md) — the lightweight story brief format
• [references/detailed-story-spec-contract.md](references/detailed-story-spec-contract.md) — the pre-code detailed story spec format
• [references/runtime-artifact-contract.md](references/runtime-artifact-contract.md) — runtime artifact, metric, budget, transcript, report, and export shape
• [examples/](examples/) — a worked PRD and tracker (Linkly)
• [CONTRIBUTING.md](CONTRIBUTING.md) — how to develop and contribute
• [docs/brand.md](docs/brand.md) — the visual identity (logo, color, type, social/SEO kit)

Install

Claude Code plugin

/plugin marketplace add aryeko/agentic-workflow-kit
/plugin install agentic-workflow-kit@agentic-workflow-kit

Codex plugin

Add the marketplace from the CLI (Codex docs), then install from the Codex plugin directory:

codex plugin marketplace add aryeko/agentic-workflow-kit

Restart Codex, then open the plugin directory, select the agentic-workflow-kit marketplace, and install the agentic-workflow-kit plugin (CLI equivalent: codex plugin add agentic-workflow-kit@agentic-workflow-kit).

Optional standalone CLI

pnpm add -D @agentic-workflow-kit/orchestrator
pnpm exec agentic-workflow-kit --help

The package also publishes the MCP executable used by plugin installs:

npx -y --package @agentic-workflow-kit/orchestrator@ agentic-workflow-kit-mcp

See the [package README](packages/orchestrator/README.md) for CLI and MCP runtime details.

Local development

pnpm install
pnpm check
pnpm agentic-workflow-kit -- --help

Optional local Codex plugin smoke requires the Codex CLI. It is intentionally outside pnpm check so the default development gate works on machines that only have the package toolchain installed.

Local plugin testing

The repository includes local-only plugin metadata for development testing:

• Claude Code: load this repo with claude --plugin-dir ./, then invoke namespaced skills such as

/agentic-workflow-kit:workflow-init; the root .mcp.json wires the package MCP runtime.

• Codex: .agents/plugins/marketplace.json is the marketplace manifest — the same one a public

codex plugin marketplace add aryeko/agentic-workflow-kit reads. Locally you add it from the repo directory; it points at the materialized fixture at ./plugins/agentic-workflow-kit, including the fixture-specific .codex-plugin/.mcp.json MCP manifest. The Codex plugin manifest declares mcpServers: "./.codex-plugin/.mcp.json"; that file uses Codex's mcpServers shape so Codex can launch the package MCP server without reusing Claude Code's root .mcp.json. Both plugin surfaces run npx -y --package @agentic-workflow-kit/orchestrator@ agentic-workflow-kit-mcp. Codex entries omit cwd; workflow MCP tools operate on the target repo when Codex provides that cwd, and callers can still pass the tool cwd argument explicitly when needed. If cwd is omitted and no workflow config is visible, the tools return an actionable error.

tmp_home="$(mktemp -d)"
CODEX_HOME="$tmp_home" codex plugin marketplace add .
CODEX_HOME="$tmp_home" codex plugin list
CODEX_HOME="$tmp_home" codex plugin add agentic-workflow-kit@agentic-workflow-kit
CODEX_HOME="$tmp_home" codex plugin list

The same Codex install and prompt-visibility check is available as:

pnpm smoke:codex-plugin

That smoke installs through a temporary CODEX_HOME, verifies prompt visibility, starts the installed package MCP command from a non-plugin consumer cwd, and reaches tools/list. If Codex reports connection closed: initialize response, do not assume the package MCP server JavaScript is invalid. First check the installed MCP config, package specifier, npm cache/network access, and installed plugin cache version:

codex plugin list
find "$CODEX_HOME/plugins/cache/agentic-workflow-kit/agentic-workflow-kit" -maxdepth 1 -type d
cat "$CODEX_HOME/plugins/cache/agentic-workflow-kit/agentic-workflow-kit//.codex-plugin/.mcp.json"

The marketplace source version, installed cache version, and already-running Codex session can drift. After changing plugin manifests or MCP wiring, reinstall the plugin into the relevant CODEX_HOME and relaunch Codex so the active session reloads the installed cache.

Keep manual plugin smokes pending until they are run in the relevant tool environment.

Layout

• skills/ — the plugin's instructions and slash-command entry points.
• references/ — the config schema (human + machine), tracker, PRD, technical solution contracts, and templates.
• presets/ — the three starter configs.
• examples/ — a worked PRD and tracker.
• packages/orchestrator/ — the TypeScript runtime source: the config schema, loader, presets, MCP server adapter, autonomous multi-session orchestrator, standalone CLI, and package MCP executable.
• docs/ — architecture, the docs hub, and the getting-started guide.

Project status

agentic-workflow-kit plugin and package manifests are versioned together: the six skills (workflow-init, define-product, design-technical-solution, plan-delivery-track, implement-next, workflow-autopilot), the package-backed MCP runtime, the contracts, the three presets, the worked examples, and the optional standalone @agentic-workflow-kit/orchestrator CLI package are implemented and covered by the test suite (pnpm check).

It is an early 0.x release — the install paths above are live. Feedback and issues are welcome as the agent-driven skills get broader real-world mileage.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: aryeko
• Source: aryeko/agentic-workflow-kit
• License: MIT

Install and usage instructions live in the source repository linked above.