Skip to content

ronnielutaro/github-epic-creation

v0.1.0

Design, preview, create, resume, and verify phased GitHub Epics with native sub-issues and blocked-by relationships.

GitHubOpen Website

GitHub Epic Creation Plugin

A Codex plugin for designing and publishing implementation-ready GitHub Epics with phased native sub-issues, explicit blocked by relationships, release checkpoints, and evidence-based closure rules.

The plugin packages one focused Codex skill and a deterministic Python helper. It does not run a server or introduce a second GitHub integration: live operations still use the user's authenticated GitHub CLI and remain behind an explicit mutation gate.

It helps turn a broad initiative into:

  • one parent Epic that acts as the release contract;
  • independently implementable child issues grouped into meaningful phases;
  • a directed, cycle-free dependency graph;
  • native GitHub parent/sub-issue and dependency relationships;
  • a final integrated certification gate when the work warrants one; and
  • a resumable record of every live issue created.

Why package it as a plugin?

The original project was a directly installed skill. Plugin packaging keeps that reasoning workflow while adding a portable manifest, versioned installation, marketplace discovery, and Codex-facing metadata. The plugin remains deliberately skills-only because the existing command-line helper already provides a small, auditable boundary for GitHub access.

What makes this different

Markdown checklists are useful summaries, but they do not create GitHub's native hierarchy or dependency indicators. This plugin uses the GitHub features that show an issue's parent, sub-issues, blocked by, and blocking relationships directly in the interface.

It also separates safe planning from live mutation:

  1. validate checks the plan and dependency graph locally.
  2. render creates reviewable Markdown previews.
  3. preflight checks GitHub access and repository metadata without changing issues.
  4. apply creates or resumes the live issue graph only with an exact repository confirmation.
  5. verify reads the live graph back and confirms its hierarchy and blockers.

Requirements

  • Codex with plugin support.
  • Python 3.10 or newer.
  • An authenticated GitHub CLI version that supports issue --parent and dependency flags.
  • At least triage permission in the target repository to manage sub-issues and dependencies.

Install in Codex

Add this repository's marketplace and install the plugin:

codex plugin marketplace add ronnielutaro/epics-creation-plugin --ref v0.1.0
codex plugin add github-epic-creation@ronnielutaro-epic-creation

Start a new Codex task after installation so the plugin's skill is loaded. Invoke it explicitly with $github-epic-creation, or let Codex select it for multi-issue Epic planning requests.

The marketplace and plugin source are pinned to the v0.1.0 release so installation is reproducible.

Quick start from a checkout

Copy the example plan and replace its repository, outcomes, phases, issue contracts, and dependencies:

Copy-Item skills\github-epic-creation\references\epic-plan.example.json my-epic.json
python skills\github-epic-creation\scripts\epic_tool.py validate my-epic.json
python skills\github-epic-creation\scripts\epic_tool.py render my-epic.json --output-dir .epic-preview
python skills\github-epic-creation\scripts\epic_tool.py preflight my-epic.json

Review the rendered parent and child issue bodies before creating anything on GitHub.

After the repository owner explicitly approves live creation:

python skills\github-epic-creation\scripts\epic_tool.py apply my-epic.json --confirm-repository OWNER/REPO

Verify the graph later with:

python skills\github-epic-creation\scripts\epic_tool.py verify my-epic.json

The default resume file is my-epic.json.state.json. Keep it until verification succeeds. Do not discard it during a partial run, because it prevents accidental duplicate issue creation.

Plan model

An Epic plan contains:

  • a stable plan key and exact OWNER/REPO target;
  • the parent Epic's objective, primary invariant, boundaries, decisions, exit criteria, and completion policy;
  • ordered phases with explicit checkpoints;
  • child issues with outcomes, bounded scope, acceptance criteria, verification, and closure evidence; and
  • blocked_by edges referencing another child key, an existing issue number, or a full GitHub issue URL.

See the plan format and complete example and the reusable example JSON.

Dependency rules

The validator rejects:

  • duplicate phase or child keys;
  • unknown internal blockers;
  • dependency cycles;
  • children blocked by work in a later phase;
  • malformed external issue references; and
  • Epics exceeding GitHub's 100 direct sub-issue limit.

No dependency edge means the work may proceed in parallel when its phase checkpoint permits. Numbering alone does not create a blocker.

Safety model

  • Planning and rendering are local operations.
  • Preflight is read-only.
  • Live creation requires the apply subcommand and an exact --confirm-repository OWNER/REPO value.
  • Repository labels, assignees, milestones, and issue types are checked before the first issue is created.
  • State is written after every successful creation so normal interruptions can resume.
  • Existing parent relationships are never replaced by this tool.
  • The tool does not close issues, delete issues, merge pull requests, or automatically declare an Epic complete.

Live creation is not transactional. If GitHub accepts a mutation but the network response is uncertain, inspect GitHub for the embedded codex-epic-key markers before retrying.

Project structure

.
|-- plugin.json                              Portable plugin manifest
|-- .codex-plugin/plugin.json                Codex compatibility manifest
|-- .agents/plugins/marketplace.json         Repository marketplace catalog
|-- skills/github-epic-creation/
|   |-- SKILL.md                             Skill entrypoint and safety contract
|   |-- agents/openai.yaml                   Skill display metadata
|   |-- references/                          Plan schema, example, and guidance
|   `-- scripts/epic_tool.py                 Deterministic helper tool
|-- docs/                                    Architecture, data flow, and decisions
`-- tests/                                   Behavior and package invariants

The root plugin.json is the portable plugin contract. .codex-plugin/plugin.json is retained as a compatibility manifest for current Codex tooling.

Development and verification

Run the complete local verification suite:

python -m py_compile skills\github-epic-creation\scripts\epic_tool.py
python -m unittest discover -s tests -v
python skills\github-epic-creation\scripts\epic_tool.py validate skills\github-epic-creation\references\epic-plan.example.json
python "$env:USERPROFILE\.codex\skills\.system\skill-creator\scripts\quick_validate.py" skills\github-epic-creation
python "$env:USERPROFILE\.codex\skills\.system\plugin-creator\scripts\validate_plugin.py" .

Design guidance

Read Epic decomposition and evidence before publishing a cross-layer or release-critical initiative. The central rule is simple: phases communicate risk retirement, while native dependency edges encode prerequisites that truly block safe completion.

For the implementation design, see the documentation index, system architecture, and data-flow design.

Codex plugin references:

GitHub references:

Contributing

Keep changes focused and preserve the separation between read-only planning and external mutation. Run the complete test suite and both package validators before committing. Changes to live-mutation behavior should include tests for failure, retry, resume, and duplicate-prevention boundaries.