Skip to content
Skills Library
Programming · Planning

epic-dev

/epic-dev

Execute the project epic development workflow for Codex. Use when the user asks for "epic dev", "epic-dev", "/epic-dev", "run the epic workflow", "create an epic", "resume the epic", "--resume", "--next-phase", "--finalize", phased feature delivery, sprint phases, GitHub sub-issues, or git worktrees for multi-phase implementation.

Licence
BSD-3-Clause
Last repository change
23.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 23.10.2026, without references to retired models or APIs.

Licence

BSD-3-Clause, otwarta.

What it does and when to use it

Execute the project epic development workflow for Codex. Use when the user asks for "epic dev", "epic-dev", "/epic-dev", "run the epic workflow", "create an epic", "resume the epic", "--resume", "--next-phase", "--finalize", phased feature delivery, sprint phases, GitHub sub-issues, or git worktrees for multi-phase implementation.

Triggers from the description

epic devepic-devrun the epic workflowcreate an epicresume the epic--resume--next-phase--finalize
Original author description

Execute the project epic development workflow for Codex. Use when the user asks for "epic dev", "epic-dev", "/epic-dev", "run the epic workflow", "create an epic", "resume the epic", "--resume", "--next-phase", "--finalize", phased feature delivery, sprint phases, GitHub sub-issues, or git worktrees for multi-phase implementation.

How it works

  1. Operating Rules
  2. Phase 0: Repository Detection
  3. Mode Parsing
  4. Phase 1: Epic Setup
  5. Phase 2: Sprint Execution
  6. Phase 3: Epic Finalization
  7. Error Handling
  8. References
Original SKILL.md headings · 158 lines, 1,270 words
SKILL.md preview
---
name: epic-dev
description: Execute the project epic development workflow for Codex. Use when the user asks for "epic dev", "epic-dev", "/epic-dev", "run the epic workflow", "create an epic", "resume the epic", "--resume", "--next-phase", "--finalize", phased feature delivery, sprint phases, GitHub sub-issues, or git worktrees for multi-phase implementation.
user-invocable: false
---

# Epic Development Workflow

Codex entrypoint for the same phased epic workflow exposed to Claude Code as
`/epic-dev`. Use `workflow-reference` for command snippets, state shape, and
variation details, then follow this procedure as the execution contract.

## Operating Rules

- Execute repository detection, GitHub lookups, worktree setup, tests, commits, PR creation, and cleanup directly when prerequisites are valid.
- Ask before strategic points only: epic plan approval, per-phase implementation plan approval, an accepted Critical finding that cannot be fixed within the phase, and final epic merge.
- When anything blocks progress, follow the `project:engineering-loop` skill's `unblock-rules.md` reference: every wait has a limit and a next action.
- Use absolute paths in shell commands. Do not rely on a previous `cd`.
- Track progress with the active planning tool when available.
- Do not use `codex/` branch prefixes. Prefer `feature/issue-{N}-...`, `patch/...`, or `chore/...` per project rules.
- Do not use emojis in issues, PRs, commits, or generated state.
- Route models per `agent-fanout`. A Luna (`max`) driver orchestrates and
  delegates epic design, unresolved architecture, and high-risk invariants to
  Sol (`xhigh`); Luna (`max`) implements, reviews, and validates. Terra may
  elaborate an approved phase architecture.
- Semantic line breaks remain the default for prose source, except text posted
  to GitHub (issue and pull-request bodies, comments, reviews, and
  discussions). There, keep each paragraph and list item on one source line,
  separate paragraphs with blank lines, and do not insert sentence- or
  clause-level newlines inside a paragraph.

## Phase 0: Repository Detection

1. Invoke the `project-preflight` skill's bundled
   `<project-plugin-root>/bin/project-preflight --format json` executable by
   absolute path from the target repository. Do not assume the plugin's
   `bin/` directory is on `PATH`. This is a read-only startup probe for the
   repository, shell, terminal, GitHub CLI, and native-agent surface. It never
   spawns agents or prints credentials.
2. Validate required values before continuing:
   - `INTEGRATION_BRANCH`
   - `REPO_ROOT`
   - `CURRENT_BRANCH`
3. If preflight reports `ERROR` or a required field is empty, report the exact
   diagnostic and stop. Optional capability states (`gh_*`, `native_agent_*`)
   are diagnostics, not repository-detection failures.
4. Before a GitHub operation, require `has_gh=true`. If it is false, use the
   separate `gh_command_status`, `gh_network_status`, `gh_auth_status`, and
   `gh_token_status` fields to tell the user whether to install `gh`, repair
   network access, or run `gh auth login`; never collapse a network failure into
   a generic unauthenticated message. If `gh_child_credential_status=mismatch`,
   explain that the current shell and its child do not see the same credentials.
5. If the project requires sub-issue operations and `gh-sub-issue` is absent,
   install it with `gh extension install agbiotech/gh-sub-issue` after normal
   approval rules for networked commands.
6. Read existing state from `.claude/epic.local.md` if present. New Codex runs
   may continue using that file for compatibility with the Claude command.

## Mode Parsing

Interpret the user request:

| Input | Mode | Action |
| --- | --- | --- |
| `--resume` | Resume | Read state, find the current incomplete phase, and continue. |
| `--next-phase` | Next phase | Read state, find the next pending phase, and start it. |
| `--finalize` | Finalize | Skip to the final epic PR and cleanup. |
| Any other text | New epic | Treat the text as the epic description. |
| Empty request | New epic | Ask for the epic description. |

For resume modes, validate state fields before acting: `epic_issue`,
`epic_branch`, `integration_branch`, `phases`, and `current_phase`.

## Phase 1: Epic Setup

1. Gather the epic description and phase breakdown. Suggest phases when the user has not provided them, using the sizing rule in `workflow-reference` (one phase = one independently reviewable and testable PR, roughly one subsystem or up to ~500 net changed lines; if two candidate phases can only be tested together, they are one phase). If the description contains only one such unit, use the single-phase shortcut.
2. Present the plan for confirmation:

   ```text
   Epic: {title}
   Integration branch: {INTEGRATION_BRANCH}
   Epic branch: feature/issue-{N}-epic-{slug}

   Phases:
   1. {phase 1 title}
   2. {phase 2 title}

   Proceed?
   ```

3. After confirmation, create the epic issue, phase sub-issues, and links:
   - `gh issue create --title "Epic: {title}" --label "feature"`
   - `gh issue create --title "Phase {X}: {title}" --label "feature"`
   - `gh sub-issue add {epic_issue} --sub-issue-number {phase_issue}`
4. Create the epic worktree from the integration branch unless this is a single-phase feature.
5. Write `.claude/epic.local.md` using the format in `workflow-reference`.
6. Ensure `.claude/*.local.md` is ignored without overwriting existing `.gitignore` customizations.

For a single-phase feature, skip the epic worktree and sub-issues. Create one
feature branch from the integration branch and target the integration branch
directly.

## Phase 2: Sprint Execution

For each phase, starting from the current state:

1. Create or reuse the phase worktree from the epic branch.
2. Mark the phase `in_progress`.
3. Have the lead define the phase architecture and open judgment calls. After
   approval, a Terra phase planner may expand it into exact files, decisions,
   tests, and gates. Ask for approval of the worker-executable plan.
4. Delegate implementation in the isolated phase worktree to a named Luna
   worker using the full lifecycle brief from `agent-fanout`. The lead does not
   hand over unresolved design choices.
5. Add focused tests for changed behavior and run the relevant verification.
6. Commit atomic changes with concise messages.
7. Push and create a PR targeting the epic branch:

   ```bash
   git -C "{phase_worktree}" push -u origin {phase_branch}
   gh pr create --base {epic_branch} --title "Phase {X}: {title}" --body "{body}"
   ```

8. Review the phase PR with `pr-review-toolkit` and follow its
   `review-convergence.md` reference: one full round, fixes committed on the
   phase branch (a large fix: one fix PR based on the phase branch), a delta
   round only if round 1 was substantial, no third
   round. Send security, concurrency, authorization, data-integrity, or
   architectural findings to Sol before fixing them.
9. Squash merge the phase PR when the convergence merge gate passes. Do not
   ask the user.
10. Update state, remove the phase worktree, close/remove completed one-off
    agent threads, and continue to the next phase.

## Phase 3: Epic Finalization

1. Create the final PR from the epic branch to the integration branch.
2. Run project tests or the best available integration verification from the epic worktree.
3. Review the final PR with one integration-scoped reviewer (`pr-review-toolkit`): cross-phase integration only, not content the phase reviews covered; same two-round limit.
4. Present the final review summary and ask for merge approval.
5. Merge the final PR with a regular merge (`--merge`) to preserve per-phase history; only squash if the user explicitly asks.
6. Close the epic issue if GitHub did not close it automatically.
7. Remove the epic worktree.
8. Close/remove completed one-off agent threads, then archive or delete the
   local state file after confirming the workflow is complete.

## Error Handling

- Detection failure: stop with the exact `project-preflight` error for missing
  repository fields; preserve the separate GitHub and optional-agent
  diagnostics for repair guidance.
- Git conflict: merge or rebase the base branch, resolve, and rerun gates. Ask the user only when a resolution needs a product decision.
- Test or CI failure: fix and rerun (two attempts), escalate to Sol with the log, then hand off with the failing command and output.
- GitHub API failure: retry twice; then show what was already created and ask whether to retry or abort.
- Merge failure: do not update state or clean up worktrees. Leave the phase marked `in_progress`.
- Dirty worktree cleanup: do not force-remove without explicit user approval.
- Corrupt state: show the invalid fields and ask whether to repair state or start a new epic.

## References

- `workflow-reference` skill: branch strategy, state file format, worktree commands, GitHub commands, and variation handling.
- `pr-review-toolkit` skill: phase and final PR review before merge.
Files in this package (2)
  • SKILL.md 9 KB
  • agents/openai.yaml 1 KB

Versions

The database has no other skills named epic-dev.

Database snapshot: 13.11.2026 · package version 6132daa94b04 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100workflow-reference
    This skill should be used when executing the epic-dev workflow, creating epic branches, managing sprint phases, working with git worktrees for phased feature development, or when the user mentions "epic dev", "epic-dev", "/epic-dev", "epic workflow", "sprint phases", "phased…
  • 100create-workflow-epic
    Create a complete workflow initiative with an epic, core workflow sub-issues, and launch preparation tasks. Use when the user asks to create a workflow epic, file a workflow task, or start a new workflow initiative.
  • 100spec-workflow
    This skill should be used when the user asks to "build a feature", "create a spec", "start spec-driven development", "run research phase", "generate requirements", "create design", "plan tasks", "implement spec", "check spec status", "triage a feature", "create an epic",…
  • 90ring:writing-plans
    Writing a rolling-wave phased implementation plan from a spec before coding: a phase-epic-task hierarchy where Phase 1 is detailed into dispatch-ready tasks and later phases stay epic-level for elaboration during execution. Use when a multi-file feature needs decomposition; runs…
  • 100dx-create-epic
    Use when you need to create a GitHub issue for an epic: one outcome too large for a single story, delivered by several stories and chores that link to it as native sub-issues. Triggers on "create an epic", "file an epic for this", "group these issues under an epic", and "make…
  • 100epic
    Run one host-native Prism epic lifecycle with Beads-backed Frame, Architecture, Roadmap, Approval, Delivery, and Validation phases. Use when the user runs $prism:epic, /prism:epic, /prism-epic, explicitly targets a Prism epic, or asks to continue a multi-story initiative.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.