epic-dev

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.